@excom/quark-sheet 0.1.0

package/.rush/temp/chunked-rush-logs/quark-sheet.apply-exports.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/chunked-rush-logs/quark-sheet.build_docs.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/chunked-rush-logs/quark-sheet.build_package-metas.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/apply-exports/all.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/.rush/temp/operation/apply-exports/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 38.93855100000019
+}

package/.rush/temp/operation/build_docs/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/.rush/temp/operation/build_docs/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/operation/build_docs/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 51.72877900000003
+}

package/.rush/temp/operation/build_package-metas/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/.rush/temp/operation/build_package-metas/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/build_package-metas/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 107.8026809999999
+}

package/.rush/temp/shrinkwrap-deps.json

@@ -0,0 +1,3 @@
+{
+  "../../packages/quark-sheet": "../../packages/quark-sheet:i+nbLCbAzl73Wvd7BEwK65xRFYNcSWL1m9qbAQlsxIc=:"
+}

package/config/rig.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@excom/heft-rig",
+  "rigProfile": "default"
+}

package/index.css

@@ -0,0 +1,5 @@
+@import "./src/quark-sheet.css";
+
+@layer {
+  @mixin module-quark-sheet;
+}

package/index.ts

@@ -0,0 +1,17 @@
+import { QuarkSheet } from "./quark-sheet";
+
+QuarkSheet.define();
+
+export { QuarkSheet };
+
+type T_HTMLQuarkSheetElement = typeof QuarkSheet.CustomElement;
+declare global {
+  interface HTMLQuarkSheetElement extends T_HTMLQuarkSheetElement {}
+  interface Window {
+    HTMLQuarkSheetElement: HTMLQuarkSheetElement;
+  }
+  interface HTMLElementTagNameMap {
+    "quark-sheet": HTMLQuarkSheetElement;
+  }
+}
+export type { HTMLQuarkSheetElement };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@excom/quark-sheet",
+  "version": "0.1.0",
+  "description": "<quark-sheet> — host a Quark orchestration sheet for sibling markup",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/loadable-element": "^0.1.0",
+    "@excom/neutron": "^0.1.0",
+    "@excom/quark": "^0.1.0",
+    "@excom/kit-utils": "^0.1.0",
+    "@excom/kit-logger": "^0.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/quark-sheet"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/quark-sheet/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "quark-sheet",
+    "neutron",
+    "custom-elements"
+  ],
+  "excom": {
+    "packageType": "kit-element"
+  },
+  "scripts": {
+    "build": "node node_modules/@excom/heft-rig/scripts/vite-build.mjs",
+    "build:watch": "node node_modules/@excom/heft-rig/scripts/vite-build-watch.mjs",
+    "format": "node node_modules/@excom/heft-rig/scripts/format.mjs",
+    "test": "node node_modules/@excom/heft-rig/scripts/vitest.mjs",
+    "coverage": "node node_modules/@excom/heft-rig/scripts/coverage.mjs",
+    "dev": "node node_modules/@excom/heft-rig/scripts/vite-dev.mjs",
+    "preview": "node node_modules/@excom/heft-rig/scripts/vite-preview.mjs",
+    "build:package-metas": "node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs",
+    "build:docs": "node node_modules/@excom/heft-rig/scripts/build-docs.mjs"
+  }
+}

package/quark-sheet.ts

@@ -0,0 +1,182 @@
+import { KitLogger } from "@excom/kit-logger";
+import { clearFetchCaches, fetchPlainText } from "@excom/kit-utils";
+import { LoadableElement } from "@excom/loadable-element";
+import { ConstructorType, Neutron, TEvent } from "@excom/neutron";
+import { Quark } from "@excom/quark";
+
+export type QuarkSheetLoadingEvent = TEvent & {
+  type: "quark-sheet-loading";
+  detail: void;
+};
+
+export type QuarkSheetSuccessEvent = TEvent & {
+  type: "quark-sheet-success";
+  detail: void;
+};
+
+export type QuarkSheetErrorEvent = TEvent & {
+  type: "quark-sheet-error";
+  detail: unknown;
+};
+
+/**
+ * Hosts a Quark orchestration sheet for its parent. Put markup and
+ * `<quark-sheet>` as siblings under the same parent — Quark scopes to that
+ * host. Inline sheet text, or load remote Quark via `src-url`.
+ *
+ * @summary Load / own a Quark sheet for sibling markup.
+ *
+ * @example
+ * <section>
+ *   <quark-sheet>
+ *     details[open] [bind-status] { content: "Open"; }
+ *     details:not([open]) [bind-status] { content: "Closed"; }
+ *   </quark-sheet>
+ *   <details>
+ *     <summary>Panel</summary>
+ *     <span bind-status></span>
+ *   </details>
+ * </section>
+ *
+ * @command --reload - Drops the shared text cache entry for `src-url` and
+ *   fetches the sheet again (the cache is page-wide: every element loading
+ *   the same URL shares it). No-op without `src-url`.
+ *
+ * @fires quark-sheet-loading - After `is-loading` becomes true (fetch in
+ *   flight).
+ * @type QuarkSheetLoadingEvent
+ * @fires quark-sheet-success - After the sheet parses and registers
+ *   successfully (`is-success`).
+ * @type QuarkSheetSuccessEvent
+ * @fires quark-sheet-error - After parse / fetch failure (`is-error`).
+ *   `event.detail` is the error.
+ * @type QuarkSheetErrorEvent
+ */
+export const QuarkSheet = Neutron.compose([
+  LoadableElement,
+  Neutron({
+    tag: "quark-sheet",
+    props: {
+      /**
+       * @option
+       * URL of a remote `.quark` / text sheet. When set, contents are
+       * fetched into the live sheet (replacing inline text).
+       * @values <URL>
+       */
+      srcUrl: String,
+      /**
+       * @option
+       * Run top-level rules in the root context (the whole document)
+       * instead of implicitly wrapping the sheet in `@scope { }`. Rules
+       * nested inside an explicit `@scope { }` block remain scoped to the
+       * host either way.
+       */
+      isGlobal: Boolean,
+      // from LoadableElement; repeated so the docs here are local
+      /**
+       * @state
+       * Fetch in progress.
+       */
+      isLoading: Boolean,
+      /**
+       * @state
+       * Sheet parsed and registered on the host.
+       */
+      isSuccess: Boolean,
+      /**
+       * @state
+       * Fetch or Quark parse/register failed.
+       */
+      isError: Boolean,
+      // private
+      srcPromise: Promise as ConstructorType<Promise<string>>,
+      /**
+       * @state
+       * Resolved sheet source text (from fetch or inline). Not reflected —
+       * sheets can be large.
+       */
+      srcText: {
+        type: String,
+        // sheets can be large: never reflect
+        attr: false,
+      },
+      /**
+       * @state
+       * Live `Quark` instance while registered.
+       */
+      quarkInstance: Quark,
+    },
+  }),
+])
+  /* No `src-url`: take the inline sheet text. */
+  .onConnected(
+    ({ srcUrl, textContent }) =>
+      !srcUrl && textContent?.trim() && { srcText: textContent }
+  )
+  .onConnected((element) => {
+    /* Reconnect: re-register the live instance on the (maybe new) parent. */
+    if (element.quarkInstance) {
+      element.quarkInstance.register({
+        sheetElement: element,
+      });
+    }
+  })
+  /* `src-url` set: fetch the remote sheet. */
+  .onPropSet("srcUrl", ({ srcUrl }) => ({
+    srcPromise: fetchPlainText(srcUrl),
+  }))
+  /* Reload: drop the shared cache entry and fetch again. */
+  .onCommand("--reload", ({ srcUrl }) => {
+    if (!srcUrl) return;
+    clearFetchCaches(srcUrl);
+    // clear `srcText` too: identical remote text must still re-register
+    return { srcText: null, srcPromise: fetchPlainText(srcUrl) };
+  })
+  /* Fetch settled: drop `srcPromise`, write `srcText`. */
+  .onPromiseResolved("srcPromise", (_, result) => ({
+    srcPromise: null,
+    srcText: result.srcPromise as any,
+  }))
+  /* In-flight `srcPromise` → loading. */
+  .onPropChanged(
+    "srcPromise",
+    ({ srcPromise }) => !!srcPromise && { _setLoading: [] }
+  )
+  /* Fetch failed → error. */
+  .onPromiseRejected("srcPromise", (_, result) => {
+    KitLogger.error(`quark-sheet error:`, result.srcPromise);
+    return { srcPromise: null, _setError: [result.srcPromise] };
+  })
+  /* `srcText` / `isGlobal` changed: parse and register again. */
+  .onPropChanged(["srcText", "isGlobal"], (element) => {
+    const { srcText, srcPromise, quarkInstance, isGlobal } = element;
+    // wait out an in-flight fetch before (re)registering
+    if (srcText && !srcPromise) {
+      try {
+        quarkInstance?.unregister();
+        return [
+          {
+            quarkInstance: new Quark({
+              src: srcText,
+              // host-scoped unless `is-global` (the historical default)
+              options: { isScoped: !isGlobal },
+            }),
+          },
+          { _setSuccess: [null] },
+        ];
+      } catch (e: any) {
+        KitLogger.error(`quark-sheet error:`, e);
+        return { _setError: [e] };
+      }
+    }
+  })
+  .onPropSet("quarkInstance", (element) => {
+    element.quarkInstance?.register({
+      sheetElement: element,
+    });
+  })
+  /* When element is disconnected, clean up quark. A move re-registers on
+     reconnect (the host may have changed), so `isMoving` cannot skip it. */
+  .onDisconnected(({ quarkInstance }) => {
+    quarkInstance?.unregister();
+  });

package/rush-logs/quark-sheet.apply-exports.cache.log

@@ -0,0 +1 @@
+Caching has been disabled for this project's "apply-exports" command.

package/rush-logs/quark-sheet.apply-exports.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/rush-logs/quark-sheet.build_docs.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:docs" command, so caching has been disabled.

package/rush-logs/quark-sheet.build_docs.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/rush-logs/quark-sheet.build_package-metas.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:package-metas" command, so caching has been disabled.

package/rush-logs/quark-sheet.build_package-metas.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/src/quark-sheet.css

@@ -0,0 +1,8 @@
+/* Selector aliases. */
+@custom-selector :--quark-sheet quark-sheet, .tag-quark-sheet;
+
+@define-mixin module-quark-sheet {
+  :--quark-sheet {
+    display: none;
+  }
+}

package/support/custom-elements.json

@@ -0,0 +1,220 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "quark-sheet.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "QuarkSheet",
+          "customElement": true,
+          "tagName": "quark-sheet",
+          "mixins": [
+            {
+              "name": "LoadableElement",
+              "package": "@excom/loadable-element"
+            }
+          ],
+          "summary": "Load / own a Quark sheet for sibling markup.",
+          "description": "Hosts a Quark orchestration sheet for its parent. Put markup and `<quark-sheet>` as siblings under the same parent — Quark scopes to that host. Inline sheet text, or load remote Quark via `src-url`.",
+          "attributes": [
+            {
+              "name": "src-url",
+              "type": {
+                "text": "string"
+              },
+              "description": "URL of a remote `.quark` / text sheet. When set, contents are fetched into the live sheet (replacing inline text).",
+              "fieldName": "srcUrl",
+              "values": [
+                "<URL>"
+              ]
+            },
+            {
+              "name": "is-global",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Run top-level rules in the root context (the whole document) instead of implicitly wrapping the sheet in `@scope { }`. Rules nested inside an explicit `@scope { }` block remain scoped to the host either way.",
+              "fieldName": "isGlobal"
+            },
+            {
+              "name": "is-loading",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Fetch in progress.",
+              "fieldName": "isLoading"
+            },
+            {
+              "name": "is-success",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Sheet parsed and registered on the host.",
+              "fieldName": "isSuccess"
+            },
+            {
+              "name": "is-error",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Fetch or Quark parse/register failed.",
+              "fieldName": "isError"
+            },
+            {
+              "name": "quark-instance",
+              "type": {
+                "text": "Quark"
+              },
+              "description": "Live `Quark` instance while registered.",
+              "fieldName": "quarkInstance"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "srcUrl",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "URL of a remote `.quark` / text sheet. When set, contents are fetched into the live sheet (replacing inline text).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isGlobal",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Run top-level rules in the root context (the whole document) instead of implicitly wrapping the sheet in `@scope { }`. Rules nested inside an explicit `@scope { }` block remain scoped to the host either way.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isLoading",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Fetch in progress.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isSuccess",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Sheet parsed and registered on the host.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isError",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Fetch or Quark parse/register failed.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "quarkInstance",
+              "type": {
+                "text": "Quark"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Live `Quark` instance while registered.",
+              "_neutron": {
+                "surface": "state"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "quark-sheet-loading",
+              "description": "After `is-loading` becomes true (fetch in flight).",
+              "type": {
+                "text": "QuarkSheetLoadingEvent",
+                "expanded": "CustomEvent & { type: \"quark-sheet-loading\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+              }
+            },
+            {
+              "name": "quark-sheet-success",
+              "description": "After the sheet parses and registers successfully (`is-success`).",
+              "type": {
+                "text": "QuarkSheetSuccessEvent",
+                "expanded": "CustomEvent & { type: \"quark-sheet-success\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+              }
+            },
+            {
+              "name": "quark-sheet-error",
+              "description": "After parse / fetch failure (`is-error`). `event.detail` is the error.",
+              "type": {
+                "text": "QuarkSheetErrorEvent",
+                "expanded": "CustomEvent & { type: \"quark-sheet-error\"; detail: unknown; bubbles: true; cancelable: true; composed: true }"
+              }
+            }
+          ],
+          "_neutron": {
+            "commands": [
+              {
+                "name": "--reload",
+                "description": "Drops the shared text cache entry for `src-url` and fetches the sheet again (the cache is page-wide: every element loading the same URL shares it). No-op without `src-url`."
+              }
+            ],
+            "cssAliases": [
+              {
+                "name": ":--quark-sheet",
+                "selectors": [
+                  "quark-sheet",
+                  ".tag-quark-sheet"
+                ],
+                "kind": "element"
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "QuarkSheet",
+          "declaration": {
+            "name": "QuarkSheet",
+            "module": "quark-sheet.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "quark-sheet",
+          "declaration": {
+            "name": "QuarkSheet",
+            "module": "quark-sheet.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/demos/provider.html

@@ -0,0 +1,13 @@
+<section>
+  <provider-fetch api-url="/api/todos/1">
+    <p>Title: <span bind-title></span></p>
+  </provider-fetch>
+  <quark-sheet>
+    provider-fetch[is-success] {
+      $todo: prop("provision").body;
+      [bind-title] {
+        content: $todo.title;
+      }
+    }
+  </quark-sheet>
+</section>

package/support/demos/simple.html

@@ -0,0 +1,14 @@
+<section>
+  <quark-sheet>
+    details[open] summary {
+      content: "Panel Open";
+    }
+    details:not([open]) summary {
+      content: "Panel Closed";
+    }
+  </quark-sheet>
+  <details>
+    <summary></summary>
+    <p>This is the panel content.</p>
+  </details>
+</section>