@jxsuite/ui 0.0.0

package/src/icons-build.ts

@@ -0,0 +1,74 @@
+/**
+ * The pure half of the icon build: how a Phosphor asset is named, and how its path data is lifted
+ * out of the SVG. `scripts/build-icons.ts` supplies the file system; this module can be tested with
+ * strings.
+ */
+
+/** The three weights the kit ships. `fill` is the "active" drawing of the same glyph. */
+export const ICON_WEIGHTS = ["regular", "bold", "fill"] as const;
+export type IconWeight = (typeof ICON_WEIGHTS)[number];
+
+/** `name → weights` as authored in `icons/list.json`. */
+export type IconList = Record<string, IconWeight[]>;
+
+/** The committed manifest: one path-data string per name and weight, on one shared viewBox. */
+export interface IconManifest {
+  viewBox: string;
+  icons: Record<string, Partial<Record<IconWeight, string>>>;
+}
+
+/** The Phosphor viewBox every glyph is drawn on. */
+export const ICON_VIEW_BOX = "0 0 256 256";
+
+/**
+ * The asset path inside `@phosphor-icons/core` for a name and weight. Regular glyphs carry no
+ * suffix; every other weight is `<name>-<weight>.svg` under its own directory.
+ */
+export function assetPath(name: string, weight: IconWeight): string {
+  return weight === "regular"
+    ? `assets/regular/${name}.svg`
+    : `assets/${weight}/${name}-${weight}.svg`;
+}
+
+const PATH_D = /<path\b[^>]*\bd="([^"]+)"/g;
+
+/**
+ * Every `d` attribute in an SVG, joined into one path-data string. A glyph is one `<path>` in
+ * practice; a second path starts with its own `M`, so concatenation draws both.
+ *
+ * @throws {Error} When the SVG carries no path at all — an icon that draws nothing is a build
+ *   error.
+ */
+export function extractPathData(svg: string): string {
+  const parts: string[] = [];
+  for (const match of svg.matchAll(PATH_D)) {
+    parts.push(match[1]!);
+  }
+  if (parts.length === 0) {
+    throw new Error("icon svg carries no <path d>");
+  }
+  return parts.join(" ");
+}
+
+/**
+ * Build the manifest from the list, reading each asset through `read`. Names and weights are
+ * emitted sorted, so the committed file is stable across runs.
+ */
+export function buildManifest(
+  list: IconList,
+  read: (relativePath: string) => string,
+): IconManifest {
+  const icons: IconManifest["icons"] = {};
+  for (const name of Object.keys(list).toSorted()) {
+    const weights = list[name]!;
+    const entry: Partial<Record<IconWeight, string>> = {};
+    for (const weight of ICON_WEIGHTS) {
+      if (!weights.includes(weight)) {
+        continue;
+      }
+      entry[weight] = extractPathData(read(assetPath(name, weight)));
+    }
+    icons[name] = entry;
+  }
+  return { icons, viewBox: ICON_VIEW_BOX };
+}

package/src/icons.ts

@@ -0,0 +1,55 @@
+/**
+ * Icon lookup over the committed manifest. `jx-icon` reaches this through `$src`, so the manifest
+ * stays a plain import rather than a state entry: a hundred kilobytes of path data has no business
+ * being a reactive object.
+ *
+ * @docs extending/ui-kit
+ */
+import manifest from "../icons/manifest.json";
+import { ICON_VIEW_BOX, ICON_WEIGHTS } from "./icons-build.ts";
+import type { IconManifest, IconWeight } from "./icons-build.ts";
+
+export { ICON_VIEW_BOX, ICON_WEIGHTS } from "./icons-build.ts";
+export type { IconWeight } from "./icons-build.ts";
+
+const { icons } = manifest as IconManifest;
+
+/** Every icon name the kit ships, sorted. */
+export const ICON_NAMES: readonly string[] = Object.keys(icons);
+
+/** Whether the manifest carries a glyph for the name, at the weight when one is given. */
+export function hasIcon(name: string, weight?: IconWeight): boolean {
+  const entry = icons[name];
+  if (!entry) {
+    return false;
+  }
+  return weight === undefined || weight in entry;
+}
+
+const warned = new Set<string>();
+
+/**
+ * The path data for a name and weight. A weight the manifest lacks falls back to `regular`, which
+ * every listed icon carries; a name it lacks warns once and draws nothing, so a typo shows as a gap
+ * rather than a crash or a wrong glyph.
+ *
+ * Called from the `jx-icon` document with the element's own `name` and `weight` state.
+ */
+export function iconPath(name: unknown, weight: unknown): string {
+  const key = typeof name === "string" ? name : "";
+  const entry = icons[key];
+  if (!entry) {
+    if (key && !warned.has(key)) {
+      warned.add(key);
+      console.warn(`jx-icon: no icon named "${key}"`);
+    }
+    return "";
+  }
+  const w = (ICON_WEIGHTS as readonly string[]).includes(String(weight))
+    ? (weight as IconWeight)
+    : "regular";
+  return entry[w] ?? entry.regular ?? "";
+}
+
+/** The viewBox `jx-icon` draws on; the manifest's, so a rebuilt manifest cannot drift from it. */
+export const iconViewBox: string = (manifest as IconManifest).viewBox || ICON_VIEW_BOX;

package/src/index.ts

@@ -0,0 +1,70 @@
+/**
+ * `@jxsuite/ui` — register the kit's elements into the current realm, with no network.
+ *
+ * The kit ships JSON sources, not compiled classes. `registerUi()` preloads every document under
+ * its `jx-ui:/components/<tag>.json` URL and every behaviour module under the specifier the
+ * documents spell in `$src`, then defines each element through the runtime's own `defineElement`. A
+ * document's `$elements` and `$src` therefore resolve exactly as they would from a server, and the
+ * bundler saw every file (embedding.md §6).
+ *
+ * @docs extending/ui-kit
+ */
+import { defineElement, preloadDocument, preloadModule } from "@jxsuite/runtime";
+import * as menu from "./behaviors/menu.ts";
+import { documents } from "./documents.ts";
+import * as icons from "./icons.ts";
+import { installTheme } from "./theme.ts";
+
+export { documents, KIT_TAGS } from "./documents.ts";
+export { hasIcon, ICON_NAMES, ICON_WEIGHTS, iconPath, iconViewBox } from "./icons.ts";
+export type { IconWeight } from "./icons.ts";
+export {
+  installTheme,
+  THEME_LAYER,
+  themeCSS,
+  themeInstalled,
+  themeTokenNames,
+  themeTokens,
+} from "./theme.ts";
+
+/** The base every kit document resolves its references against. */
+export const KIT_BASE = "jx-ui:/components/";
+
+/** Behaviour modules, under the `$src` specifiers the documents use. */
+export const KIT_MODULES: Readonly<Record<string, Record<string, unknown>>> = {
+  "jx-ui:/behaviors/menu.ts": menu,
+  "jx-ui:/icons.ts": icons,
+};
+
+export interface RegisterUiOptions {
+  /** Adopt the theme into the document as well. Default is true. */
+  theme?: boolean;
+  /** The document to adopt the theme into. Default is the global document. */
+  document?: Document;
+}
+
+let registration: Promise<void> | null = null;
+
+/**
+ * Define every kit element in this realm, once. Idempotent: later calls return the same promise.
+ *
+ * @param {RegisterUiOptions} [options]
+ * @returns {Promise<void>} Settles when every element is defined
+ */
+export function registerUi(options: RegisterUiOptions = {}): Promise<void> {
+  if (options.theme !== false) {
+    installTheme(options.document);
+  }
+  registration ??= (async () => {
+    for (const [specifier, mod] of Object.entries(KIT_MODULES)) {
+      preloadModule(specifier, mod);
+    }
+    for (const [tag, doc] of Object.entries(documents)) {
+      preloadDocument(`${KIT_BASE}${tag}.json`, doc);
+    }
+    for (const doc of Object.values(documents)) {
+      await defineElement(doc, KIT_BASE);
+    }
+  })();
+  return registration;
+}

package/src/testing/popover-shim.ts

@@ -0,0 +1,139 @@
+/**
+ * What happy-dom 20 lacks and the kit's overlays are built on: the popover API. A test-only shim,
+ * exported as `@jxsuite/ui/testing/popover-shim` so a host's own DOM harness installs the same
+ * one.
+ *
+ * `showPopover()` / `hidePopover()` / `togglePopover()` are defined on `HTMLElement.prototype` only
+ * when missing. The shim keeps the parts of the standard's algorithm the kit relies on — a
+ * `popover` attribute is required, `beforetoggle` fires synchronously and `toggle` in a microtask
+ * with `oldState`/`newState`, showing an `auto` popover light-dismisses unrelated `auto` popovers,
+ * hiding one hides the popovers nested inside it, a mousedown outside or an Escape hides the
+ * topmost `auto` one — and marks a showing popover with `data-popover-open`, because
+ * `:popover-open` never matches here. Test-only: paint, the top layer and real focus restoration
+ * are the browser's to verify.
+ */
+
+interface PopoverState {
+  open: Set<HTMLElement>;
+  /** The invoker each showing popover was shown from, when `showPopover({ source })` named one. */
+  invokers: WeakMap<HTMLElement, Element>;
+}
+
+declare global {
+  interface Window {
+    __jxPopoverShim?: PopoverState;
+  }
+}
+
+function toggleEvent(type: "beforetoggle" | "toggle", oldState: string, newState: string): Event {
+  const event = new Event(type, { bubbles: false, cancelable: type === "beforetoggle" });
+  Object.assign(event, { newState, oldState });
+  return event;
+}
+
+function isAuto(el: HTMLElement): boolean {
+  return el.getAttribute("popover") !== "manual";
+}
+
+export function installPopoverShim(): void {
+  const proto = HTMLElement.prototype as HTMLElement & {
+    showPopover?: (options?: { source?: Element }) => void;
+    hidePopover?: () => void;
+    togglePopover?: (force?: boolean) => boolean;
+  };
+  if (typeof proto.showPopover === "function") {
+    return;
+  }
+  const state: PopoverState = { invokers: new WeakMap(), open: new Set() };
+  window.__jxPopoverShim = state;
+
+  const hide = (el: HTMLElement): void => {
+    if (!state.open.has(el)) {
+      return;
+    }
+    for (const other of [...state.open].toReversed()) {
+      if (other !== el && el.contains(other)) {
+        hide(other);
+      }
+    }
+    el.dispatchEvent(toggleEvent("beforetoggle", "open", "closed"));
+    state.open.delete(el);
+    delete el.dataset.popoverOpen;
+    queueMicrotask(() => el.dispatchEvent(toggleEvent("toggle", "open", "closed")));
+  };
+
+  proto.showPopover = function showPopover(
+    this: HTMLElement,
+    options?: { source?: Element },
+  ): void {
+    if (!this.hasAttribute("popover")) {
+      throw new DOMException("Not a popover element", "NotSupportedError");
+    }
+    if (state.open.has(this)) {
+      return;
+    }
+    // An invoker is not "outside": a mousedown on the button that opened a popover leaves it to
+    // The button's own click, which is what makes a toggle a toggle.
+    if (options?.source) {
+      state.invokers.set(this, options.source);
+    } else {
+      state.invokers.delete(this);
+    }
+    if (isAuto(this)) {
+      const showing = [...state.open];
+      for (const other of showing) {
+        if (isAuto(other) && !other.contains(this)) {
+          hide(other);
+        }
+      }
+    }
+    this.dispatchEvent(toggleEvent("beforetoggle", "closed", "open"));
+    state.open.add(this);
+    this.dataset.popoverOpen = "";
+    queueMicrotask(() => this.dispatchEvent(toggleEvent("toggle", "closed", "open")));
+  };
+  proto.hidePopover = function hidePopover(this: HTMLElement): void {
+    if (!this.hasAttribute("popover")) {
+      throw new DOMException("Not a popover element", "NotSupportedError");
+    }
+    hide(this);
+  };
+  proto.togglePopover = function togglePopover(this: HTMLElement, force?: boolean): boolean {
+    const show = force ?? !state.open.has(this);
+    if (show) {
+      this.showPopover!();
+    } else {
+      this.hidePopover!();
+    }
+    return show;
+  };
+
+  document.addEventListener(
+    "mousedown",
+    (event) => {
+      for (const el of [...state.open].toReversed()) {
+        const target = event.target instanceof Node ? event.target : null;
+        const inside =
+          target !== null &&
+          (el.contains(target) || state.invokers.get(el)?.contains(target) === true);
+        if (isAuto(el) && !inside) {
+          hide(el);
+        }
+      }
+    },
+    true,
+  );
+  document.addEventListener(
+    "keydown",
+    (event) => {
+      if (event.key !== "Escape") {
+        return;
+      }
+      const top = [...state.open].toReversed().find((el) => isAuto(el));
+      if (top) {
+        hide(top);
+      }
+    },
+    true,
+  );
+}

package/src/theme.ts

@@ -0,0 +1,63 @@
+/**
+ * The kit's theme: one stylesheet of design tokens, built from the kit's own `project.json`.
+ *
+ * The tokens live in the project's `style` block, exactly where a site keeps its design tokens
+ * (site-architecture.md §10.2), so opening the kit as a project in Studio shows the same values the
+ * shell runs on. This module turns that block into CSS with the runtime's own style builder and
+ * wraps it in `@layer jx-ui`, so any unlayered author rule — a site's override, Studio's chrome —
+ * wins over a token by cascade order rather than by specificity.
+ *
+ * @docs extending/ui-kit
+ */
+import { buildStyleRules } from "@jxsuite/runtime/css";
+import type { JxStyle } from "@jxsuite/schema/types";
+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 theme as CSS text: every token on `:root`, inside `@layer jx-ui`. */
+export function themeCSS(): string {
+  const rules = buildStyleRules(themeTokens, { scope: ":root" }).map((rule) => rule.text);
+  return `@layer ${THEME_LAYER} {\n${rules.join("\n")}\n}\n`;
+}
+
+/** The custom-property names the theme declares at the root, in declaration order. */
+export function themeTokenNames(): string[] {
+  return Object.keys(themeTokens).filter((key) => key.startsWith("--"));
+}
+
+const installed = new WeakMap<Document, CSSStyleSheet | HTMLStyleElement>();
+
+/**
+ * Adopt the theme into a document, once. A constructable sheet where the host has one, a `<style>`
+ * element otherwise; calling it again for the same document is a no-op.
+ *
+ * @param {Document} [doc] Default is the global document
+ */
+export function installTheme(doc: Document = document): void {
+  if (installed.has(doc)) {
+    return;
+  }
+  const css = themeCSS();
+  if (typeof CSSStyleSheet === "function" && "replaceSync" in CSSStyleSheet.prototype) {
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(css);
+    doc.adoptedStyleSheets = [...doc.adoptedStyleSheets, sheet];
+    installed.set(doc, sheet);
+    return;
+  }
+  const style = doc.createElement("style");
+  style.dataset.jxTheme = THEME_LAYER;
+  style.textContent = css;
+  doc.head.append(style);
+  installed.set(doc, style);
+}
+
+/** Whether {@link installTheme} has run for a document. */
+export function themeInstalled(doc: Document = document): boolean {
+  return installed.has(doc);
+}

package/stylebook/jx-action-button.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StylebookActionButton",
+  "tagName": "main",
+  "$elements": [
+    { "$ref": "../components/jx-icon.json" },
+    { "$ref": "../components/jx-action-button.json" }
+  ],
+  "state": {
+    "bold": false,
+    "note": {
+      "$prototype": "Function",
+      "parameters": ["event"],
+      "body": [
+        {
+          "operator": "=",
+          "target": { "$ref": "#/state/bold" },
+          "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)"
+    },
+    "& > p": { "color": "var(--jx-fg-dim)", "margin": "0 0 var(--jx-space-5)" },
+    "& [role=\"toolbar\"]": {
+      "display": "flex",
+      "alignItems": "center",
+      "gap": "var(--jx-space-1)",
+      "padding": "var(--jx-space-1)",
+      "background": "var(--jx-bg-panel)",
+      "border": "1px solid var(--jx-border)",
+      "borderRadius": "var(--jx-radius-md)",
+      "width": "fit-content",
+      "margin": "0 0 var(--jx-space-4)"
+    }
+  },
+  "children": [
+    { "tagName": "h1", "textContent": "jx-action-button" },
+    {
+      "tagName": "p",
+      "textContent": "Icon-first tool buttons: quiet in a toolbar, a toggle with aria-pressed, an emphasized selection, and a text-and-icon form. Bold is ${state.bold ? 'on' : 'off'}."
+    },
+    {
+      "tagName": "div",
+      "attributes": { "role": "toolbar", "aria-label": "Formatting" },
+      "children": [
+        {
+          "tagName": "jx-action-button",
+          "$props": { "label": "Bold", "icon": "text-b", "toggles": true },
+          "onchange": { "$ref": "#/state/note" }
+        },
+        {
+          "tagName": "jx-action-button",
+          "$props": { "label": "Italic", "icon": "text-italic", "toggles": true, "selected": true }
+        },
+        { "tagName": "jx-action-button", "$props": { "label": "Link", "icon": "link" } },
+        {
+          "tagName": "jx-action-button",
+          "$props": { "label": "Undo", "icon": "arrow-u-up-left", "disabled": true }
+        }
+      ]
+    },
+    {
+      "tagName": "div",
+      "attributes": { "role": "toolbar", "aria-label": "Emphasized and sized" },
+      "children": [
+        {
+          "tagName": "jx-action-button",
+          "$props": {
+            "label": "Selected, emphasized",
+            "icon": "eye",
+            "toggles": true,
+            "selected": true,
+            "emphasized": true
+          }
+        },
+        {
+          "tagName": "jx-action-button",
+          "$props": { "label": "Not quiet", "icon": "gear", "quiet": false }
+        },
+        {
+          "tagName": "jx-action-button",
+          "$props": { "label": "Small", "icon": "plus", "size": "sm" }
+        },
+        {
+          "tagName": "jx-action-button",
+          "$props": { "label": "Large", "icon": "plus", "size": "lg" }
+        },
+        {
+          "tagName": "jx-action-button",
+          "$props": { "label": "Save", "icon": "floppy-disk", "quiet": false },
+          "children": [{ "tagName": "span", "textContent": "Save" }]
+        }
+      ]
+    }
+  ]
+}

package/stylebook/jx-button.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StylebookButton",
+  "tagName": "main",
+  "$elements": [
+    { "$ref": "../components/jx-icon.json" },
+    { "$ref": "../components/jx-button.json" }
+  ],
+  "state": {
+    "variants": ["accent", "primary", "secondary", "negative"],
+    "clicks": 0,
+    "count": {
+      "$prototype": "Function",
+      "body": [{ "operator": "+=", "target": { "$ref": "#/state/clicks" }, "value": 1 }]
+    }
+  },
+  "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)"
+    },
+    "& > p": { "color": "var(--jx-fg-dim)", "margin": "0 0 var(--jx-space-5)" },
+    "& [role=\"group\"]": {
+      "display": "flex",
+      "alignItems": "center",
+      "gap": "var(--jx-space-3)",
+      "margin": "0 0 var(--jx-space-4)"
+    },
+    "& [role=\"group\"] > span": {
+      "width": "80px",
+      "color": "var(--jx-fg-muted)",
+      "fontSize": "var(--jx-text-sm)"
+    }
+  },
+  "children": [
+    { "tagName": "h1", "textContent": "jx-button" },
+    {
+      "tagName": "p",
+      "textContent": "Every variant in every state. The accent is spent once per surface; secondary is the default. Clicked ${state.clicks} times."
+    },
+    {
+      "$prototype": "Array",
+      "items": { "$ref": "#/state/variants" },
+      "key": { "$ref": "$map/item" },
+      "map": {
+        "tagName": "div",
+        "attributes": { "role": "group", "aria-label": "${$map.item} buttons" },
+        "children": [
+          { "tagName": "span", "textContent": "${$map.item}" },
+          {
+            "tagName": "jx-button",
+            "$props": { "variant": { "$ref": "$map/item" } },
+            "onclick": { "$ref": "#/state/count" },
+            "children": [{ "tagName": "span", "textContent": "Label" }]
+          },
+          {
+            "tagName": "jx-button",
+            "$props": { "variant": { "$ref": "$map/item" } },
+            "children": [
+              {
+                "tagName": "jx-icon",
+                "attributes": { "slot": "icon" },
+                "$props": { "name": "plus" }
+              },
+              { "tagName": "span", "textContent": "With icon" }
+            ]
+          },
+          {
+            "tagName": "jx-button",
+            "$props": { "variant": { "$ref": "$map/item" }, "quiet": true },
+            "children": [{ "tagName": "span", "textContent": "Quiet" }]
+          },
+          {
+            "tagName": "jx-button",
+            "$props": { "variant": { "$ref": "$map/item" }, "disabled": true },
+            "children": [{ "tagName": "span", "textContent": "Disabled" }]
+          },
+          {
+            "tagName": "jx-button",
+            "$props": { "variant": { "$ref": "$map/item" }, "loading": true },
+            "children": [{ "tagName": "span", "textContent": "Loading" }]
+          },
+          {
+            "tagName": "jx-button",
+            "$props": { "variant": { "$ref": "$map/item" }, "size": "sm" },
+            "children": [{ "tagName": "span", "textContent": "Small" }]
+          },
+          {
+            "tagName": "jx-button",
+            "$props": { "variant": { "$ref": "$map/item" }, "size": "lg" },
+            "children": [{ "tagName": "span", "textContent": "Large" }]
+          }
+        ]
+      }
+    }
+  ]
+}