@excom/quark-sheet 0.1.0

package/support/dist-docs/quark-sheet.md

@@ -0,0 +1,147 @@
+# quark-sheet
+
+Drop a Quark sheet next to your markup — bind, render, and react without a component runtime.
+
+
+```html
+<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>
+```
+
+
+## Features
+
+- **Sibling scope** Sheet + targets share a parent — Quark watches that host
+- **Global sheets** `is-global` runs top-level rules document-wide
+- **Inline or remote** Paste Quark in the element, or load `src-url`
+- **Lifecycle state** `is-loading` / `is-success` / `is-error` + matching events (from [loadable-element](/nucleus/packages/loadable-element))
+- **Reload** The `--reload` command drops the shared cache entry for `src-url` and fetches again
+- **Auto (un)register** Connect registers; disconnect tears down cleanly
+
+## Installation
+
+
+`@excom/quark-sheet` v0.1.0
+
+```bash
+pnpm add @excom/quark-sheet
+```
+
+```bash
+npm install @excom/quark-sheet
+```
+
+```bash
+yarn add @excom/quark-sheet
+```
+
+### Import
+
+```ts
+import "@excom/quark-sheet";
+```
+
+
+
+## Usage
+
+Place `<quark-sheet>` under the same parent as the elements it should orchestrate.
+Inline Quark text is enough for most apps.
+
+```html
+<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>
+```
+
+By default the sheet is scoped to its parent. Add `is-global` to run
+top-level rules in the root context (e.g. reading a provider above the
+host); rules inside an explicit `@scope { }` block stay host-scoped either
+way. Language details live in the [`quark`](/nucleus/packages/quark) docs.
+
+### API Reference
+
+
+#### Attributes
+
+| Name | Surface | Type | Default | Values | Description |
+| --- | --- | --- | --- | --- | --- |
+| `src-url` | option | `string` |  | `<URL>` | URL of a remote `.quark` / text sheet. When set, contents are fetched into the live sheet (replacing inline text). |
+| `is-global` | option | `boolean` |  |  | 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. |
+| `is-loading` | state | `boolean` |  |  | Fetch in progress. |
+| `is-success` | state | `boolean` |  |  | Sheet parsed and registered on the host. |
+| `is-error` | state | `boolean` |  |  | Fetch or Quark parse/register failed. |
+| `quark-instance` | state | `Quark` |  |  | Live `Quark` instance while registered. |
+
+#### Provision
+
+| Name | Type | Description | Inherited from |
+| --- | --- | --- | --- |
+| `provision` | `unknown` | The result of the most recent work on success, or the error payload on failure. Shape is defined by the composing element. Not reflected as an attribute. | `@excom/loadable-element` |
+
+#### Fires
+
+| Name | Type | Description | Inherited from |
+| --- | --- | --- | --- |
+| `quark-sheet-loading` | `QuarkSheetLoadingEvent` (`CustomEvent & { type: "quark-sheet-loading"; detail: void; bubbles: true; cancelable: true; composed: true }`) | After `is-loading` becomes true (fetch in flight). |  |
+| `quark-sheet-success` | `QuarkSheetSuccessEvent` (`CustomEvent & { type: "quark-sheet-success"; detail: void; bubbles: true; cancelable: true; composed: true }`) | After the sheet parses and registers successfully (`is-success`). |  |
+| `quark-sheet-error` | `QuarkSheetErrorEvent` (`CustomEvent & { type: "quark-sheet-error"; detail: unknown; bubbles: true; cancelable: true; composed: true }`) | After parse / fetch failure (`is-error`). `event.detail` is the error. |  |
+| `quark-sheet-loading` | `LoadableLoadingEvent` (`CustomEvent & { type: "{tag}-loading"; detail: void; bubbles: true; cancelable: true; composed: true }`) | After `is-loading` is set (work started). | `@excom/loadable-element` |
+| `quark-sheet-success` | `LoadableSuccessEvent` | After `is-success` is set. `event.detail` is the new `provision`. | `@excom/loadable-element` |
+| `quark-sheet-error` | `LoadableErrorEvent` | After `is-error` is set. `event.detail` is the error payload (also stored as `provision`). | `@excom/loadable-element` |
+
+#### Commands
+
+| Command | Action |
+| --- | --- |
+| `--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`. |
+
+#### CSS Aliases
+
+| Alias | Kind | Matches | Description |
+| --- | --- | --- | --- |
+| `:--quark-sheet` | element | `quark-sheet`, `.tag-quark-sheet` |  |
+
+
+
+### Examples
+
+#### Provider data
+
+`prop("provision")` reads a `<provider-fetch>` provision on success and fills a title.
+
+
+```html
+<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/docs/README.md

@@ -0,0 +1,53 @@
+# quark-sheet
+
+Drop a Quark sheet next to your markup — bind, render, and react without a component runtime.
+
+<include-content data-demo="simple"></include-content>
+
+## Features
+
+- **Sibling scope** Sheet + targets share a parent — Quark watches that host
+- **Global sheets** `is-global` runs top-level rules document-wide
+- **Inline or remote** Paste Quark in the element, or load `src-url`
+- **Lifecycle state** `is-loading` / `is-success` / `is-error` + matching events (from [loadable-element](/nucleus/packages/loadable-element))
+- **Reload** The `--reload` command drops the shared cache entry for `src-url` and fetches again
+- **Auto (un)register** Connect registers; disconnect tears down cleanly
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+Place `<quark-sheet>` under the same parent as the elements it should orchestrate.
+Inline Quark text is enough for most apps.
+
+```html
+<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>
+```
+
+By default the sheet is scoped to its parent. Add `is-global` to run
+top-level rules in the root context (e.g. reading a provider above the
+host); rules inside an explicit `@scope { }` block stay host-scoped either
+way. Language details live in the [`quark`](/nucleus/packages/quark) docs.
+
+### API Reference
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>
+
+### Examples
+
+#### Provider data
+
+`prop("provision")` reads a `<provider-fetch>` provision on success and fills a title.
+
+<include-content data-demo="provider"></include-content>

package/support/package-meta.json

@@ -0,0 +1,185 @@
+{
+  "shortName": "quark-sheet",
+  "package": {
+    "name": "@excom/quark-sheet",
+    "version": "0.1.0",
+    "description": "<quark-sheet> — host a Quark orchestration sheet for sibling markup",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "provider": "<section>\n  <provider-fetch api-url=\"/api/todos/1\">\n    <p>Title: <span bind-title></span></p>\n  </provider-fetch>\n  <quark-sheet>\n    provider-fetch[is-success] {\n      $todo: prop(\"provision\").body;\n      [bind-title] {\n        content: $todo.title;\n      }\n    }\n  </quark-sheet>\n</section>\n",
+    "simple": "<section>\n  <quark-sheet>\n    details[open] summary {\n      content: \"Panel Open\";\n    }\n    details:not([open]) summary {\n      content: \"Panel Closed\";\n    }\n  </quark-sheet>\n  <details>\n    <summary></summary>\n    <p>This is the panel content.</p>\n  </details>\n</section>\n"
+  },
+  "readme": "<h1 id=\"md-quark-sheet\">quark-sheet</h1>\n<p>Drop a Quark sheet next to your markup — bind, render, and react without a component runtime.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Sibling scope</strong> Sheet + targets share a parent — Quark watches that host</li>\n<li><strong>Global sheets</strong> <code>is-global</code> runs top-level rules document-wide</li>\n<li><strong>Inline or remote</strong> Paste Quark in the element, or load <code>src-url</code></li>\n<li><strong>Lifecycle state</strong> <code>is-loading</code> / <code>is-success</code> / <code>is-error</code> + matching events (from <spa-a route-href=\"/nucleus/packages/loadable-element\" role=\"link\">loadable-element</spa-a>)</li>\n<li><strong>Reload</strong> The <code>--reload</code> command drops the shared cache entry for <code>src-url</code> and fetches again</li>\n<li><strong>Auto (un)register</strong> Connect registers; disconnect tears down cleanly</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Place <code>&lt;quark-sheet&gt;</code> under the same parent as the elements it should orchestrate.\nInline Quark text is enough for most apps.</p>\n<include-content data-language=\"html\"><template>&lt;section&gt;\n  &lt;quark-sheet&gt;\n    details[open] summary { content: \"Panel Open\"; }\n    details:not([open]) summary { content: \"Panel Closed\"; }\n  &lt;/quark-sheet&gt;\n  &lt;details&gt;\n    &lt;summary&gt;&lt;/summary&gt;\n    &lt;p&gt;This is the panel content.&lt;/p&gt;\n  &lt;/details&gt;\n&lt;/section&gt;</template></include-content>\n<p>By default the sheet is scoped to its parent. Add <code>is-global</code> to run\ntop-level rules in the root context (e.g. reading a provider above the\nhost); rules inside an explicit <code>@scope { }</code> block stay host-scoped either\nway. Language details live in the <spa-a route-href=\"/nucleus/packages/quark\" role=\"link\"><code>quark</code></spa-a> docs.</p>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-provider-data\">Provider data</h4>\n<p><code>prop(&quot;provision&quot;)</code> reads a <code>&lt;provider-fetch&gt;</code> provision on success and fills a title.</p>\n<p><include-content data-demo=\"provider\"></include-content></p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-quark-sheet\">quark-sheet</h1>\n<p>Drop a Quark sheet next to your markup — bind, render, and react without a component runtime.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Sibling scope</strong> Sheet + targets share a parent — Quark watches that host</li>\n<li><strong>Global sheets</strong> <code>is-global</code> runs top-level rules document-wide</li>\n<li><strong>Inline or remote</strong> Paste Quark in the element, or load <code>src-url</code></li>\n<li><strong>Lifecycle state</strong> <code>is-loading</code> / <code>is-success</code> / <code>is-error</code> + matching events (from <spa-a route-href=\"/nucleus/packages/loadable-element\" role=\"link\">loadable-element</spa-a>)</li>\n<li><strong>Reload</strong> The <code>--reload</code> command drops the shared cache entry for <code>src-url</code> and fetches again</li>\n<li><strong>Auto (un)register</strong> Connect registers; disconnect tears down cleanly</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Place <code>&lt;quark-sheet&gt;</code> under the same parent as the elements it should orchestrate.\nInline Quark text is enough for most apps.</p>\n<include-content data-language=\"html\"><template>&lt;section&gt;\n  &lt;quark-sheet&gt;\n    details[open] summary { content: \"Panel Open\"; }\n    details:not([open]) summary { content: \"Panel Closed\"; }\n  &lt;/quark-sheet&gt;\n  &lt;details&gt;\n    &lt;summary&gt;&lt;/summary&gt;\n    &lt;p&gt;This is the panel content.&lt;/p&gt;\n  &lt;/details&gt;\n&lt;/section&gt;</template></include-content>\n<p>By default the sheet is scoped to its parent. Add <code>is-global</code> to run\ntop-level rules in the root context (e.g. reading a provider above the\nhost); rules inside an explicit <code>@scope { }</code> block stay host-scoped either\nway. Language details live in the <spa-a route-href=\"/nucleus/packages/quark\" role=\"link\"><code>quark</code></spa-a> docs.</p>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-provider-data\">Provider data</h4>\n<p><code>prop(&quot;provision&quot;)</code> reads a <code>&lt;provider-fetch&gt;</code> provision on success and fills a title.</p>\n<p><include-content data-demo=\"provider\"></include-content></p>\n"
+  },
+  "installation": {
+    "name": "@excom/quark-sheet",
+    "shortName": "quark-sheet",
+    "version": "0.1.0",
+    "description": "<quark-sheet> — host a Quark orchestration sheet for sibling markup",
+    "packageType": "kit-element",
+    "cdn": "<script src=\"https://unpkg.com/@excom/kit-utils/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/neutron/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/quark-sheet@0.1.0/dist/index.umd.min.js\"></script>\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@excom/quark-sheet@0.1.0/dist/index.css\">",
+    "install": {
+      "npm": "npm install @excom/quark-sheet"
+    },
+    "imports": {
+      "js": "import \"@excom/quark-sheet\";",
+      "css": "@import \"@excom/quark-sheet\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/quark-sheet\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/quark-sheet\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "quark-sheet",
+      "summary": "Load / own a Quark sheet for sibling markup.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "is-global",
+          "type": "boolean",
+          "description": "Run top-level rules in the root context (the whole document) instead of implicitly wrapping the sheet in <code>@scope { }</code>. Rules nested inside an explicit <code>@scope { }</code> block remain scoped to the host either way.",
+          "fieldName": "isGlobal",
+          "surface": "option"
+        },
+        {
+          "name": "src-url",
+          "type": "string",
+          "description": "URL of a remote <code>.quark</code> / text sheet. When set, contents are fetched into the live sheet (replacing inline text).",
+          "fieldName": "srcUrl",
+          "surface": "option",
+          "values": "<URL>"
+        },
+        {
+          "name": "is-error",
+          "type": "boolean",
+          "description": "Fetch or Quark parse/register failed.",
+          "fieldName": "isError",
+          "surface": "state"
+        },
+        {
+          "name": "is-error",
+          "type": "boolean",
+          "description": "The most recent work failed. Mutually exclusive with <code>is-success</code>.",
+          "fieldName": "isError",
+          "surface": "state",
+          "inheritedFrom": "@excom/loadable-element"
+        },
+        {
+          "name": "is-loading",
+          "type": "boolean",
+          "description": "Fetch in progress.",
+          "fieldName": "isLoading",
+          "surface": "state"
+        },
+        {
+          "name": "is-loading",
+          "type": "boolean",
+          "description": "Work is in flight.",
+          "fieldName": "isLoading",
+          "surface": "state",
+          "inheritedFrom": "@excom/loadable-element"
+        },
+        {
+          "name": "is-success",
+          "type": "boolean",
+          "description": "Sheet parsed and registered on the host.",
+          "fieldName": "isSuccess",
+          "surface": "state"
+        },
+        {
+          "name": "is-success",
+          "type": "boolean",
+          "description": "The most recent work finished successfully. Mutually exclusive with <code>is-error</code>.",
+          "fieldName": "isSuccess",
+          "surface": "state",
+          "inheritedFrom": "@excom/loadable-element"
+        },
+        {
+          "name": "quark-instance",
+          "type": "Quark",
+          "description": "Live <code>Quark</code> instance while registered.",
+          "fieldName": "quarkInstance",
+          "surface": "state"
+        }
+      ],
+      "events": [
+        {
+          "name": "quark-sheet-error",
+          "description": "After parse / fetch failure (<code>is-error</code>). <code>event.detail</code> is the error.",
+          "type": "QuarkSheetErrorEvent",
+          "typeExpanded": "CustomEvent & { type: \"quark-sheet-error\"; detail: unknown; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "quark-sheet-error",
+          "description": "After <code>is-error</code> is set. <code>event.detail</code> is the error payload (also stored as <code>provision</code>).",
+          "type": "LoadableErrorEvent",
+          "inheritedFrom": "@excom/loadable-element"
+        },
+        {
+          "name": "quark-sheet-loading",
+          "description": "After <code>is-loading</code> becomes true (fetch in flight).",
+          "type": "QuarkSheetLoadingEvent",
+          "typeExpanded": "CustomEvent & { type: \"quark-sheet-loading\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "quark-sheet-loading",
+          "description": "After <code>is-loading</code> is set (work started).",
+          "type": "LoadableLoadingEvent",
+          "typeExpanded": "CustomEvent & { type: \"{tag}-loading\"; detail: void; bubbles: true; cancelable: true; composed: true }",
+          "inheritedFrom": "@excom/loadable-element"
+        },
+        {
+          "name": "quark-sheet-success",
+          "description": "After the sheet parses and registers successfully (<code>is-success</code>).",
+          "type": "QuarkSheetSuccessEvent",
+          "typeExpanded": "CustomEvent & { type: \"quark-sheet-success\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "quark-sheet-success",
+          "description": "After <code>is-success</code> is set. <code>event.detail</code> is the new <code>provision</code>.",
+          "type": "LoadableSuccessEvent",
+          "inheritedFrom": "@excom/loadable-element"
+        }
+      ],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [
+        {
+          "name": ":--quark-sheet",
+          "selectors": [
+            "quark-sheet",
+            ".tag-quark-sheet"
+          ],
+          "kind": "element",
+          "description": ""
+        }
+      ],
+      "listens": [],
+      "commands": [
+        {
+          "name": "--reload",
+          "description": "Drops the shared text cache entry for <code>src-url</code> and fetches the sheet again (the cache is page-wide: every element loading the same URL shares it). No-op without <code>src-url</code>."
+        }
+      ],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": [
+        {
+          "name": "provision",
+          "type": "unknown",
+          "description": "The result of the most recent work on success, or the error payload on failure. Shape is defined by the composing element. Not reflected as an attribute.",
+          "fieldName": "provision",
+          "inheritedFrom": "@excom/loadable-element"
+        }
+      ]
+    }
+  ],
+  "exportedFiles": {}
+}

package/support/tests/__snapshots__/provider.view.test.ts.snap

@@ -0,0 +1,23 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`provider view > binds a fetched todo title > complexity 1`] = `
+{
+  "attributeRuns": 0,
+  "closest": 0,
+  "getVar": 0,
+  "importNode": 0,
+  "listenerRuns": 0,
+  "matches": 0,
+  "parentElement": 0,
+  "quarkRuns": 0,
+  "queryScopeCost": 0,
+  "querySelectorAll": 0,
+  "removeAttribute": 0,
+  "ruleRuns": 0,
+  "schedulePaint": 0,
+  "setAttribute": 0,
+  "setVar": 0,
+  "textContent": 0,
+  "variableRuns": 0,
+}
+`;

package/support/tests/__snapshots__/simple.view.test.ts.snap

@@ -0,0 +1,23 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`simple view > labels the details panel open and closed > complexity 1`] = `
+{
+  "attributeRuns": 1,
+  "closest": 0,
+  "getVar": 0,
+  "importNode": 0,
+  "listenerRuns": 0,
+  "matches": 2,
+  "parentElement": 0,
+  "quarkRuns": 1,
+  "queryScopeCost": 2,
+  "querySelectorAll": 1,
+  "removeAttribute": 0,
+  "ruleRuns": 1,
+  "schedulePaint": 1,
+  "setAttribute": 1,
+  "setVar": 0,
+  "textContent": 1,
+  "variableRuns": 0,
+}
+`;

package/support/tests/provider.view.test.ts

@@ -0,0 +1,42 @@
+import "@excom/provider-fetch";
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+  spyFetch,
+  waitForEvent,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import {
+  expectComplexity,
+  flush,
+  measureComplexity,
+  mountView,
+  readDemo,
+} from "@excom/quark/support/tests/view-helpers";
+
+describe("provider view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("binds a fetched todo title", async () => {
+    spyFetch({
+      status: 200,
+      body: JSON.stringify({ id: 1, title: "Write docs" }),
+    });
+    const { root, quark } = await mountView(readDemo(import.meta.url, "provider"));
+    const provider = root.querySelector("provider-fetch")!;
+    if (!provider.hasAttribute("is-success")) {
+      await waitForEvent(provider, "provider-fetch-success");
+      await flush();
+    }
+    const meter = measureComplexity(quark!);
+    await flush();
+    const budget = meter.take();
+    meter.stop();
+    expect(root.querySelector("[bind-title]")?.textContent).toBe("Write docs");
+    expectComplexity(budget);
+  });
+});