@use "/shell" as *; @use "quark:list" as list; #release-notice { /* opens once: sheet re-runs restart a delay, so gate it on the fact it writes */ &:not([data-did-open]) { @delay 7000 { is-open: ""; data-did-open: ""; } } /* prevent clicks from bubbling to the sheet */ @on mouseup, click (stop-propagation); } provider-fetch[api-url*="package-metas/index.json"][is-success] { $package-indices: prop("provision").body; /* `excom.navGroup` moves a package out of its type's list, into that group */ $ungrouped: list.reject($package-indices.packages, "navGroup"); .package-links { [bind-elements] ul:not(ul ul) { content: iterate(getPackagesByType($ungrouped, "kit-element")); } [bind-element-bases] ul:not(ul ul) { content: iterate(getPackagesByType($ungrouped, "element-base")); } [bind-tools] ul:not(ul ul) { content: iterate(getPackagesByType($ungrouped, "tool")); } /* the standalone libraries: same rows, rendered flat (shell.css) */ [bind-libraries] ul:not(ul ul) { content: iterate(getPackagesByType($ungrouped, "library")); } [bind-library-group] ul:not(ul ul) { content: iterate(list.filter($package-indices.packages, "navGroup", "libraries")); } ul:not(ul ul) > li { $pkg: item.shortName; > spa-a { route-href: "/packages/#{item.shortName}"; } } /* one `content` rule per link: a second one would rewrite the first's text on every pass */ ul:not(ul ul, [bind-libraries] ul) > li > spa-a { content: item.shortName; } [bind-libraries] ul:not(ul ul) > li > spa-a { content: displayName(item.shortName); } /* packages whose docs span several pages: one collapsible group per section */ [bind-sections] { content: iterate(item.docSections); summary { content: item.title; } details > ul { content: iterate(item.docs); spa-a { route-href: "/packages/#{$pkg}/#{item.name}"; content: item.title; } } details:not(:has(spa-a[is-active])) { open: none; } } } /* page titles: the page, then the site. The docs home keeps the title in the document head; the other routes carry theirs in markup */ spa-route[is-active] { /* a site guide */ &[route-href$=":name"] { $title-guide: list.find($package-indices.docs, "name", $route.params.name); document-title: "#{$title-guide.title or $route.params.name} · Nucleus · docs"; } /* a package README */ &[route-href$=":packageName"] { document-title: "#{displayName($route.params.packageName)} · Nucleus · docs"; } /* one page of a package's docs */ &[route-href$=":docName"] { $title-package: list.find($package-indices.packages, "shortName", $route.params.packageName); document-title: "#{docTitle($title-package, $route.params.docName)} · #{displayName($route.params.packageName)} · Nucleus · docs"; } } /* the page's markdown file, for the footer link: the docs home and each guide the index lists, and a package's page whose index entry says `markdown` (build-docs-index sets it; the dev server's index has none, so no link there). siteDocHref and the path check say which URL is the page's own: the 404 and a package's doc pages have none */ > spa-manager[active-url] { $page-path: attr("active-url").split("#").at(0).split("?").at(0); $page-name: if($page-path == SITE_HOME: SITE_HOME_DOC; else: $page-path.split("/").at(-1)); $page-guide: list.find($package-indices.docs, "name", $page-name); $page-package: list.find($package-indices.packages, "shortName", $page-name); $page-markdown: if($page-guide and siteDocHref($page-guide.name) == $page-path: "/docs/#{$page-guide.name}.md"; $page-package.markdown and "#{SITE_BASE}/packages/#{$page-package.shortName}" == $page-path: "/#{$page-package.shortName}.md"); footer [bind-page-markdown] { href: $page-markdown; content: ternary($page-markdown, "Markdown version of this page"); } } } spa-route { $route: prop("provision"); /* paramless routes name their guide in markup (the docs home, `/`); /docs/:name gets it from params */ $route-doc-name: attr("data-doc-name"); } /* the desktop aside and the mobile sheet stamp the same nav template */ [data-site-nav] { details:has(spa-a[is-active]) { /* not kosher */ open: ""; } spa-a[is-active] { aria-current: ""; } spa-a:not([is-active]) { aria-current: none; } } /* mobile sheet: Escape / back gesture while open; a tapped link closes it */ #site-menu { &[is-open] dismiss-watcher { is-active: ""; } &:not([is-open]) dismiss-watcher { is-active: none; } @on click (target: "spa-a") { is-open: none; } } #site-menu-gesture { &:has(> #site-menu[is-open]) { progress-offset: 1; } &:not(:has(> #site-menu[is-open])) { progress-offset: 0; } @on gesture-handler-start { #site-menu { is-scrubbing: ""; } } @on gesture-handler-end { #site-menu { is-open: event.detail.snap == 1; is-scrubbing: none; } } } main { @on copy-source (handle: copySource); } #search-dialog[open] { > include-content { is-active: ""; /* for some reason this is necessary on first render */ @on include-content-did-render (handle: focusInput); } input[type="search"] { /* works on all subsequent opens */ autofocus: ""; } } #search-dialog:not([open]) input[type="search"] { autofocus: none; }

provider-fetch

Fetch data with HTML. Pair it with Quark to render the data. Zero app JS.

Features

  • Provides data Use Quark to render that data
  • Auto-fetch Fetches whenever api-url is set or changes
  • Re-fetch on demand The --fetch command (<button command="--fetch" commandfor="…">) forces a re-fetch
  • Pausable is-paused holds off auto-fetch without removing state
  • Highly configurable Headers, method, form-ref, credentials, redirect, etc

Installation

This package is available in the NucleusKit. Or it can be used by itself:

CDN Package Manager 
<script src="https://unpkg.com/@excom/kit-utils@0.3.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/neutron@0.2.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/provider-fetch@0.1.5/dist/index.umd.min.js"></script>
 
npm install @excom/provider-fetch
HTML Imports JS / CSS Imports 
<!-- import path to `node_modules` will depend on your build setup -->
<script type="module" src="/node_modules/@excom/provider-fetch"></script>
<link rel="stylesheet" href="/node_modules/@excom/provider-fetch">
 
import "@excom/provider-fetch";
Peer dependencies (0)

Packages a consumer must install alongside this one. Workspace deps are bundled.

Package Version
View Dist Files

All exports:

.
  • types: ./dist/index.d.ts
  • import: ./dist/index.js
  • default: ./dist/index.js
./index
  • types: ./dist/index.d.ts
  • import: ./dist/index.js
  • default: ./dist/index.js
./index.js
  • types: ./dist/index.d.ts
  • import: ./dist/index.js
  • default: ./dist/index.js
./index.min
  • types: ./dist/index.d.ts
  • import: ./dist/index.min.js
  • default: ./dist/index.min.js
./index.min.js
  • types: ./dist/index.d.ts
  • import: ./dist/index.min.js
  • default: ./dist/index.min.js
./index.umd.min
  • types: ./dist/index.d.ts
  • default: ./dist/index.umd.min.js
./index.umd.min.js
  • types: ./dist/index.d.ts
  • default: ./dist/index.umd.min.js
./provider-fetch
  • types: ./dist/provider-fetch.d.ts
  • import: ./dist/provider-fetch.js
  • default: ./dist/provider-fetch.js
./provider-fetch.js
  • types: ./dist/provider-fetch.d.ts
  • import: ./dist/provider-fetch.js
  • default: ./dist/provider-fetch.js
./provider-fetch.min
  • types: ./dist/provider-fetch.d.ts
  • import: ./dist/provider-fetch.min.js
  • default: ./dist/provider-fetch.min.js
./provider-fetch.min.js
  • types: ./dist/provider-fetch.d.ts
  • import: ./dist/provider-fetch.min.js
  • default: ./dist/provider-fetch.min.js
./provider-fetch.umd.min
  • types: ./dist/provider-fetch.d.ts
  • default: ./dist/provider-fetch.umd.min.js
./provider-fetch.umd.min.js
  • types: ./dist/provider-fetch.d.ts
  • default: ./dist/provider-fetch.umd.min.js

Usage

<provider-fetch api-url="/api/todos"></provider-fetch>

Hook the lifecycle state with CSS:

provider-fetch[is-loading] { /* show loading spinner */ }
provider-fetch[is-error]::before { content: "An error occurred." }

did-load is set on the first success, kept through a refresh (where is-loading replaces is-success) and cleared on an error: gate content on [did-load] to keep it on screen during a refresh.

Or Quark:

provider-fetch[is-success] {
  $todo: prop("provision").body;
  span { content: $todo.title; }
}

API Reference

provider-fetch

Attributes (13) Role — option is configurable, state is managed by the element (read-only), or hybrid which is both. Role Attribute Type Values Prop Default option api-method
HTTP method. Always uppercased before the request is sent. apiMethod fetchable-element
string "GET" option api-url
Endpoint URL. When the request has no body, the JSON payload (from form-ref or custom doFetch() args) is merged in as query params instead. apiUrl fetchable-element
string "" option fetch-credentials
RequestInit.credentials mode. fetchCredentials fetchable-element
string "omit" | "same-origin" | "include" "include" option fetch-redirect
RequestInit.redirect mode. Unset defers to the browser default (follow). fetchRedirect fetchable-element
string "follow" | "error" | "manual" null option form-ref
CSS selector for a <form> to source the request from — its action (URL), method, enctype (Content-Type), and field values (as the JSON payload) all take priority over the matching attributes below. Omit to build the request entirely from attributes / custom doFetch() args. formRef fetchable-element
string <CSS Selector> null option has-body
Force a request body even for methods that don't imply one (GET / HEAD). Already implied for POST / PUT / PATCH. hasBody fetchable-element
boolean false option header-accept
Accept request header. headerAccept fetchable-element
string "application/json" option header-cache-control
Cache-Control request header. Unset by default (browser default caching applies). headerCacheControl fetchable-element
string null option header-content-type
Content-Type request header. Dropped entirely when the request has no body. headerContentType fetchable-element
string "application/json" option is-paused
Pause auto-fetch. While set, api-url changes are ignored; the --fetch command still works. isPaused
boolean false state is-error
The most recent request failed (status 400 or above, network error, or a thrown error other than AbortError). Fires with the error event. isError fetchable-element
boolean false state is-loading
A request is currently in flight. isLoading fetchable-element
boolean false state is-success
The most recent request resolved successfully. Mutually exclusive with is-loading and is-error. isSuccess fetchable-element
boolean false
Provision (1) This provision property lives on the DOM node. Read / watch it with Quark’s prop("provision"), or listen for the neutron-provision event from app JS. Property Type provision
Response payload on success, or error payload on failure. Success shape: { status, statusText, ok, headers, url, redirected, bodyUsed, type, body }. Failure shape is either that same response shape (server responded with an error status) or { message, stack } (request never completed). Not reflected as an attribute. provision fetchable-element
FetchResponse
Events (5)
Dispatches — events that provider-fetch fires and their default actions. Dispatch Default Action
A "default action" is subsequent logic executed by the element if e.preventDefault() is not synchronously called on the event.
Name provider-fetch-error
Dispatched when the request fails — status 400 or above, network error, or a thrown error. event.detail is the error payload (see provision). Not dispatched for aborted requests. fetchable-element

Type FetchableErrorEvent
Name provider-fetch-loading
Dispatched immediately before the request is sent. fetchable-element

Type FetchableLoadingEvent
Name provider-fetch-submit
Internal — dispatched whenever a fetch is about to run (auto-fetch or --fetch). Built by getFetchArgs(). Cancelable; default action calls doFetch().

Type ProviderFetchSubmitEvent
Calls doFetch([url, requestInit]) with the event's detail. Name provider-fetch-success
Dispatched when the request resolves successfully. event.detail is the parsed response (see provision). fetchable-element

Type FetchableSuccessEvent
Listeners — events that provider-fetch listens for which will trigger subsequent actions. Listener Type Action
Commands — verbs provider-fetch accepts as a command event (HTML Command API): from a <button command commandfor>, an <event-handler command-name>, or a CommandEvent. Command Action --fetch Re-runs the request with the current attributes, even while is-paused.
Recognized Elements (0) Child or descendant elements are recognized by provider-fetch and relevant to its functionality. Element Relationship Required
Styles (0)
Classes — optional classes that change the appearance of provider-fetch. Class Description
Variables — public CSS variables for theming provider-fetch. Opt-out:
If you wish to opt-out of these styles on a case-to-case basis, use property all: revert-layer. Valence.css ships this as .unstyled and .unstyled-all for the entire tree.
Variable Syntax Default
Aliases — @custom-selector synonyms so custom elements can share semantic styles. Element aliases match the host tag / .tag-* class; state aliases match attributes (nested under the element alias). Alias Kind Matches
Release notes (1)

0.1.1

  • Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources
View Source

Examples

Comprehensive

This example shows loading state, error state, rendering, and refetching.

Beta. The Nucleus Stack is in beta for a few weeks until features are stabilized and optimized.

Thanks — we'll email you when it ships.

Something went wrong. Please try again.