lit-rdf 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # lit-rdf
 
+## 0.3.4
+
+### Patch Changes
+
+- 0bd749b: Include the lit-rdf skill in the published package and clarify when to use it.
+
 ## 0.3.3
 
 ### Patch Changes

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "lit-rdf",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "type": "module",
   "scripts": {
-    "prepare": "husky && patch-package && skills experimental_sync -y",
+    "postinstall": "skills experimental_sync -y",
+    "prepare": "husky && patch-package",
     "lint": "eslint . --quiet",
+    "lint:skills": "skill-check check skills --no-security-scan --fail-on-warning",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "test:storybook": "vitest --project=storybook",
@@ -17,6 +19,7 @@
     "release": "changeset publish"
   },
   "files": [
+    "skills/lit-rdf/",
     "CHANGELOG.md",
     "custom-elements.json",
     "src/**/*.js",
@@ -41,7 +44,7 @@
     "@rdfjs/data-model": "^2.1.1",
     "@rdfjs/dataset": "^2.0.3",
     "@rdfjs/types": "^2",
-    "@zazuko/env": "^3.0.4",
+    "@zazuko/env": "^3.0.6",
     "clownface": "^2.0.3",
     "clownface-shacl-path": "^2.4.0",
     "is-url": "^1.2.4",
@@ -60,8 +63,8 @@
     "@eslint/js": "^10",
     "@lit-labs/ssr": "^4.1.0",
     "@open-wc/testing": "^5.0.0",
-    "@rollup/plugin-commonjs": "^29.0.3",
     "@rolldown/plugin-node-polyfills": "^1.0.3",
+    "@rollup/plugin-commonjs": "^29.0.3",
     "@storybook/addon-docs": "^10.6.6",
     "@storybook/addon-vitest": "^10.6.6",
     "@storybook/web-components-vite": "^10.6.6",
@@ -86,10 +89,11 @@
     "eslint-plugin-storybook": "^10.5.7",
     "husky": "^9.1.7",
     "lint-staged": "^17.3.0",
-    "skills": "^1.7.6",
     "patch-package": "^8.0.1",
     "playwright": "^1.65.0",
     "sinon": "^22.1.0",
+    "skill-check": "^1.2.0",
+    "skills": "^1.7.6",
     "storybook": "^10.6.6",
     "string-to-stream": "^3.0.1",
     "typescript": "^5",

package/skills/lit-rdf/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: lit-rdf
+description: Use when building or explaining RDF-driven Lit interfaces with lit-rdf, including dataset binding, focus-node context, graph traversal, filtering, sorting, and custom reactive components. Covers lit-rdf examples and integrations; excludes generic RDF processing and unrelated Lit components.
+---
+
+# Build with lit-rdf
+
+Use the library's context providers and Clownface pointers to compose views. Preserve RDF terms and datasets through the binding layer instead of converting the graph into unrelated JSON models.
+
+## Choose the example
+
+- For initial setup, data sources, selecting resources, labels, links, and traversal, read [binding.md](references/binding.md).
+- For repeated cards or tables, filters, sorting, custom controllers, and application updates, read [patterns.md](references/patterns.md).
+- For a complete starting point, adapt [people-demo.ts](assets/people-demo.ts). It supplies its own RDF/JS fixture and renders a sorted, filtered list with per-person context. Import it from a browser TypeScript entrypoint with bare-module resolution, then place `<rdf-people-demo></rdf-people-demo>` in the page. It needs `lit`, `lit-rdf`, and `@zazuko/env`; it is not a standalone browser script.
+
+## Binding contract
+
+The usual hierarchy is `rdf-environment` → `rdf-dataset` → `target-node` → optional `filter-node` → a view consuming `FocusNode`. Contributing `rdf-graph` elements belong beneath the dataset. A custom view iterates `FocusNode.array` and wraps each item in `<focus-node .focusNode=${item}>` so nested resource elements consume that item.
+
+`target-node`, `filter-node`, and `focus-node` provide context; they do not stamp one copy of their children per resource. Use an explicit renderer for collections. Traversal offers rendering callbacks, but those callbacks also need per-item `focus-node` wrappers when rendering nested resource elements.
+
+Use attributes for serialized IRIs and paths, and Lit property bindings for objects and functions. Examples: `target-class="schema:Person"`, `.targetClass=${rdf.ns.schema.Person}`, `.value=${dataset}`, `.filter=${callback}`, `.focusNode=${pointer}`. Attribute converters do not run for property bindings.
+
+Import `lit-rdf` for element registration; import controllers from `lit-rdf/controllers.js` and the environment mixin from `lit-rdf/mixins.js`. The root entrypoint does not export controller classes. Avoid private `src/` imports in consumer examples.
+
+## Demonstrate the binding
+
+Use the public exports supported by the installed version of `lit-rdf`.
+
+Examples should include data matching their vocabulary, every required import, and a real collection renderer when multiple nodes are selected. Explain the expected visible output and how the dataset, focus, and nested bindings connect. These are display bindings; implement input-to-RDF writes explicitly when requested.

package/skills/lit-rdf/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "lit-rdf"
+  short_description: "Build RDF views with Lit context and data binding"
+  default_prompt: "Use $lit-rdf to build a data-bound RDF view with filtering and sorting."

package/skills/lit-rdf/assets/people-demo.ts

@@ -0,0 +1,100 @@
+import { html, LitElement } from 'lit'
+import type { GraphPointer } from 'clownface'
+import type { NamedNode } from '@rdfjs/types'
+import rdf from '@zazuko/env/web.js'
+import { FocusNode } from 'lit-rdf/controllers.js'
+import 'lit-rdf'
+
+const alice = rdf.namedNode('https://example.org/alice')
+const bob = rdf.namedNode('https://example.org/bob')
+const carol = rdf.namedNode('https://example.org/carol')
+const people: [NamedNode, string, number][] = [
+  [alice, 'Alice', 32], [bob, 'Bob', 16], [carol, 'Carol', 24],
+]
+const graph = rdf.dataset([
+  ...people.flatMap(
+    ([person, name, age]) => {
+      return [
+        rdf.quad(person, rdf.ns.rdf.type, rdf.ns.schema.Person),
+        rdf.quad(person, rdf.ns.schema.name, rdf.literal(String(name))),
+        rdf.quad(person, rdf.ns.foaf.age,
+          rdf.literal(String(age), rdf.ns.xsd.integer)),
+      ]
+    },
+  ),
+  rdf.quad(alice, rdf.ns.schema.knows, carol),
+])
+
+class RdfPeopleCards extends LitElement {
+  private readonly focusController = new FocusNode(this)
+
+  render() {
+    const people = this.focusController.array ?? []
+    if (!people.length) return html`<p>No matching people</p>`
+
+    return people.map(person => html`
+      <focus-node .focusNode=${person}>
+        <article>
+          <h2><resource-label predicate="schema:name"></resource-label></h2>
+          <p>Age: ${person.out(rdf.ns.foaf.age).value}</p>
+          <resource-link>Resource URI</resource-link>
+          <p>Friends: ${person.out(rdf.ns.schema.knows).toArray().map(friend => html`
+            <focus-node .focusNode=${friend}>
+              <resource-label predicate="schema:name"></resource-label>
+            </focus-node>
+          `)}</p>
+        </article>
+      </focus-node>
+    `)
+  }
+}
+customElements.define('rdf-people-cards', RdfPeopleCards)
+
+class RdfPeopleDemo extends LitElement {
+  static properties = {
+    minimumAge: { type: Number },
+    direction: { type: String },
+  }
+
+  declare minimumAge: number
+  declare direction: 'asc' | 'desc'
+
+  constructor() {
+    super()
+    this.minimumAge = 18
+    this.direction = 'asc'
+  }
+
+  render() {
+    return html`
+      <label>Minimum age
+        <input type="number" .value=${String(this.minimumAge)}
+          @input=${(event: Event) => {
+            this.minimumAge = (event.target as HTMLInputElement).valueAsNumber
+          }}>
+      </label>
+      <button @click=${() => {
+        this.direction = this.direction === 'asc' ? 'desc' : 'asc'
+      }}>Reverse name order</button>
+      <rdf-environment>
+        <rdf-dataset>
+          <rdf-graph .value=${graph}></rdf-graph>
+          <target-node target-class="schema:Person"
+            order-by="schema:name" order-dir=${this.direction}>
+            <filter-node .filter=${(person: GraphPointer) => {
+              const age = person.out(rdf.ns.foaf.age).value
+              return age !== undefined && Number(age) >= this.minimumAge
+            }}>
+              <rdf-people-cards></rdf-people-cards>
+            </filter-node>
+          </target-node>
+        </rdf-dataset>
+      </rdf-environment>
+    `
+  }
+}
+customElements.define('rdf-people-demo', RdfPeopleDemo)
+
+// Initially: Alice (32, friend Carol), then Carol (24).
+// Minimum age 0 includes Bob (16); 100 displays “No matching people”.
+// Reversing order changes the initial list to Carol, then Alice.

package/skills/lit-rdf/references/binding.md

@@ -0,0 +1,101 @@
+# Declarative binding
+
+## Supply data and select one resource
+
+This is a complete Lit render function for a browser application with package imports resolved by its build tool:
+
+```ts
+import { html, render } from 'lit'
+import rdf from '@zazuko/env/web.js'
+import 'lit-rdf'
+
+const alice = rdf.namedNode('https://example.org/alice')
+const dataset = rdf.dataset([
+  rdf.quad(alice, rdf.ns.rdf.type, rdf.ns.schema.Person),
+  rdf.quad(alice, rdf.ns.schema.name, rdf.literal('Alice')),
+  rdf.quad(alice, rdf.ns.schema.url, rdf.namedNode('https://alice.example.org/')),
+])
+
+render(html`
+  <rdf-environment>
+    <rdf-dataset .value=${dataset}>
+      <target-node target-node="https://example.org/alice">
+        <h2><resource-label predicate="schema:name"></resource-label></h2>
+        <resource-link property="schema:url">Homepage</resource-link>
+      </target-node>
+    </rdf-dataset>
+  </rdf-environment>
+`, document.body)
+```
+
+Expected output: a heading “Alice” and a “Homepage” anchor linking to `https://alice.example.org/`. The environment supplies RDF factories; the dataset supplies the graph; the target supplies a Clownface pointer; resource elements consume that pointer.
+
+`resource-label` defaults to `rdfs:label`. Specify `predicate="schema:name"` for schema names; there is no automatic fallback across arbitrary label predicates. `resource-link` uses the focus URI when `property` is absent or resolves no value. Supply its visible content in the default slot. `resource-value` displays the current pointer's raw `.value`; it has no predicate lookup or datatype formatting API.
+
+## Compose graph sources
+
+Use either a dataset bound directly to `rdf-dataset.value`, as above, or child graph contributions:
+
+```ts
+html`
+  <rdf-environment>
+    <rdf-dataset>
+      <rdf-graph .value=${peopleDataset}></rdf-graph>
+      <rdf-graph .value=${labelsDataset}
+        graph="https://example.org/graphs/labels"></rdf-graph>
+      <!-- Put selection and view components here. -->
+    </rdf-dataset>
+  </rdf-environment>
+`
+```
+
+Here `peopleDataset` and `labelsDataset` are RDF/JS DatasetCore objects, not strings. Graph contributions are merged; without a `graph` override their existing quad graph terms are preserved. Setting `graph` rewrites all contributed quads to that named graph. Graph contribution updates rebuild `rdf-dataset.value`, so avoid treating its direct value binding as an additional independently merged source.
+
+`rdf-graph` has no `src` URL loader or inline Turtle parser. Fetch/parse RDF in application code, then bind the resulting dataset. Its `window.graphs` lookup is an optional preloaded factory mechanism keyed by `data-graph` or `id`, not a network loader. The current update hook watches `value`; changing only `graph` does not resubmit the contribution.
+
+## Select focus nodes
+
+| Attribute            | Property binding type           | Meaning                           |
+|----------------------|---------------------------------|-----------------------------------|
+| `target-node`        | `.targetNode` = NamedNode       | Explicit resource                 |
+| `target-class`       | `.targetClass` = NamedNode      | Subjects with matching `rdf:type` |
+| `target-subjects-of` | `.targetSubjectsOf` = NamedNode | Subjects of a predicate           |
+| `target-objects-of`  | `.targetObjectsOf` = NamedNode  | Objects of a predicate            |
+
+Use one selector per element. If several are set, the implementation chooses in the table's order; it does not combine them. Prefixed attributes use the library's known prefixes. Use a full IRI or a NamedNode property binding for application vocabularies; declaring a prefix in Turtle does not register it with attribute converters.
+
+## Traverse from a single resource
+
+Inside a per-resource focus, a single-valued property can be displayed as:
+
+```ts
+html`
+  <traverse-graph property-path="foaf:age">
+    <resource-value></resource-value>
+    <span slot="empty">Age unknown</span>
+  </traverse-graph>
+`
+```
+
+`property-path` is parsed as a SPARQL/SHACL path. For example, `schema:knows/schema:name` follows friends to their names, and `^schema:knows` follows incoming relationships. A `.propertyPath` binding expects the parsed SHACL path object, not the serialized string.
+
+For multiple results, choose a callback rather than relying on the `.value` of a multi-pointer:
+
+```ts
+import type { GraphPointer } from 'clownface'
+
+html`
+  <traverse-graph property-path="schema:knows"
+    .renderObjectNode=${(friend: GraphPointer) => html`
+      <focus-node .focusNode=${friend}>
+        <p><resource-label predicate="schema:name"></resource-label></p>
+      </focus-node>
+    `}>
+    <p slot="empty">No friends listed</p>
+  </traverse-graph>
+`
+```
+
+The default slot receives the entire resulting pointer, not one scoped pointer per child. `.renderObjectNodes` receives the whole multi-pointer and takes precedence over `.renderObjectNode`. Neither callback applies the ambient sort automatically.
+
+Current implementation caveat: `traverse-graph.willUpdate` checks a `focusNode` changed-property key, while its controller calls `requestUpdate()` without that key. Initial property-path rendering is supported, but a later focus-only change may leave traversal stale. For dynamic views, derive related values directly from the current `GraphPointer` inside the collection renderer, as the demo does, or verify a library fix before relying on reactive traversal.

package/skills/lit-rdf/references/patterns.md

@@ -0,0 +1,100 @@
+# Collection and application patterns
+
+## Consume a collection, then scope each item
+
+Use [people-demo.ts](../assets/people-demo.ts) for the complete version of this pattern:
+
+```ts
+import { html, LitElement } from 'lit'
+import { FocusNode } from 'lit-rdf/controllers.js'
+import 'lit-rdf'
+
+class ResourceCards extends LitElement {
+  private readonly focusController = new FocusNode(this)
+
+  render() {
+    const items = this.focusController.array ?? []
+    return items.length ? items.map(item => html`
+      <focus-node .focusNode=${item}>
+        <article>
+          <resource-link>
+            <resource-label predicate="schema:name"></resource-label>
+          </resource-link>
+        </article>
+      </focus-node>
+    `) : html`<p>No matching resources</p>`
+  }
+}
+customElements.define('resource-cards', ResourceCards)
+```
+
+Place `<resource-cards>` under a target and optional filter. `FocusNode.pointer` is the entire selection. `FocusNode.array` returns per-node pointers and applies ambient sorting. The controller requests host updates when focus or sorting changes. Handle its initially undefined pointer; context becomes available through element connection.
+
+For a table, put a `focus-node` inside each cell that needs a resource component, or scope custom row components internally. Do not insert a `focus-node` wrapper between native `table`/`tbody`/`tr` elements in parsed HTML: table parsing can relocate invalid children. For keyed collections, use a stable key appropriate to the data and ensure relation displays update when that key retains an existing component.
+
+## Filter and sort
+
+```ts
+import type { GraphPointer } from 'clownface'
+import rdf from '@zazuko/env/web.js'
+
+const minimumAge = 18
+html`
+  <target-node target-class="schema:Person"
+    order-by="schema:name" order-dir="asc">
+    <filter-node .filter=${(person: GraphPointer) => {
+      const age = person.out(rdf.ns.foaf.age).value
+      return age !== undefined && Number(age) >= minimumAge
+    }}>
+      <resource-cards></resource-cards>
+    </filter-node>
+  </target-node>
+`
+```
+
+The filter is a Clownface callback passed as a property. An omitted callback passes the current selection through. For interactive thresholds, keep the threshold in reactive host state and create a new callback in `render()` so `.filter` changes when the threshold changes. A stable callback closing over mutable state alone does not notify `filter-node` to recompute.
+
+`order-by` converts a predicate IRI to a key extractor. For a custom key use `.orderBy=${(person: GraphPointer) => person.out(rdf.ns.schema.name).value?.toLowerCase()}`. Consumers must use `FocusNode.array` to honor that sort context. Merely wrapping arbitrary slotted markup in `target-node` does not reorder it.
+
+Sorting converts RDF literals to comparable JS values. Use typed numeric/date literals for numeric/date ordering; plain string literals sort as strings. Missing keys sort last in both directions.
+
+## Supply an existing pointer
+
+If the host already has a Clownface pointer, bind it directly with `<focus-node .focusNode=${pointer}>`. Descendant resource elements can consume it without `target-node`. Keep `rdf-environment` and `rdf-dataset` ancestors when other descendants require those contexts. Do not pass a bare IRI or a dataset as `.focusNode`.
+
+## Custom context consumers and providers
+
+Public imports:
+
+```ts
+import { Dataset, Environment, FocusNode } from 'lit-rdf/controllers.js'
+import { provideEnvironment } from 'lit-rdf/mixins.js'
+```
+
+- `new Environment(this)` consumes an ancestor environment; `.value` throws if no provider exists. Access it after connection, rather than assuming availability in the host constructor.
+- `new Dataset(this, dataset => { /* update host state */ })` consumes dataset changes and exposes `.value` and a Clownface `.pointer`. Update reactive host state or request an update in the callback if the host renders dataset-derived values.
+- `new FocusNode(this)` consumes focus and sorting, exposes `.pointer` and sorted `.array`, and requests updates automatically. `.onChange` can recompute derived state.
+- `class Host extends provideEnvironment(LitElement)` supplies an environment after assigning its public `rdf` property. `rdf-environment` already provides the default web environment and is simpler for ordinary templates.
+
+`lit-rdf/context.js` and `lit-rdf/controllers/FocusNode.js` are not exported package paths in this version. Use the public controller barrel rather than inventing context imports for consumers.
+
+## Updates and editing
+
+The library displays RDF data; it does not provide form-to-RDF two-way binding. To implement editing, explicitly add/delete RDF quads in application code and publish a new dataset reference through `rdf-dataset.value` or `rdf-graph.value`. In-place changes to a DatasetCore do not themselves trigger Lit property updates or context delivery. With contributed graphs, update the contribution rather than overwriting the parent's aggregate.
+
+Example after removing a value in application code:
+
+```ts
+const next = rdf.dataset([...current])
+next.delete(oldQuad)
+next.add(replacementQuad)
+// Assign next to reactive application state bound as .value=${...}.
+```
+
+Keep these current limits in mind for demos involving live data:
+
+- `target-node.setFocusNode()` only publishes selections with at least one term; a transition from matches to no matches can retain the previous focus. Do not promise that switching to an absent class clears the view without checking/fixing this behavior.
+- `filter-node` can publish an empty pointer, so it is suitable for demonstrating a working zero-results state.
+- For focus-only traversal updates, see the caveat in [binding.md](binding.md). The asset reads ages and friends from each current pointer in the custom renderer instead.
+
+Prefer showing a limitation precisely to adding a broad workaround or silently changing library behavior as part of an example.