npm - @ulb-darmstadt/shacl-form - Versions diffs - 3.0.0 → 3.0.2 - Mend

@ulb-darmstadt/shacl-form 3.0.0 → 3.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md +185 -111
package/dist/bundle.js +82 -68
package/dist/constants.d.ts +1 -0
package/dist/index.js +29 -16
package/dist/plugins/assets/property-template-BtuDp76T.js +1 -0
package/dist/plugins/file-upload.js +1 -1
package/dist/plugins/leaflet.js +1 -1
package/package.json +11 -6
package/dist/plugins/assets/property-template-DXiwjIuW.js +0 -1

package/README.md CHANGED Viewed

@@ -1,10 +1,5 @@
 # SHACL Form Generator
-```console
-npm i @ulb-darmstadt/shacl-form
-```
-HTML5 web component for editing/viewing [RDF](https://www.w3.org/RDF/) data that conform to [SHACL shapes](https://www.w3.org/TR/shacl/).
+An HTML5 web component to edit and view [RDF](https://www.w3.org/RDF/) data that conform to [SHACL shapes](https://www.w3.org/TR/shacl/).
 ## [See demo here](https://ulb-darmstadt.github.io/shacl-form/)
@@ -13,13 +8,13 @@ HTML5 web component for editing/viewing [RDF](https://www.w3.org/RDF/) data that
 ```html
 <html>
   <head>
-    <!-- load bundled web component (or when developing your own app, just do "npm i @ulb-darmstadt/shacl-form")  -->
+    <!-- load the bundled web component (for app development, use: npm i @ulb-darmstadt/shacl-form) -->
     <script src="https://cdn.jsdelivr.net/npm/@ulb-darmstadt/shacl-form/dist/bundle.js" type="module"></script>
   </head>
   <body>
     <!--
-      SHACL shapes can be defined on the attribute 'data-shapes'
-      or can be loaded by setting attribute 'data-shapes-url'
+      Provide SHACL shapes via the data-shapes attribute
+      or load them from a URL with data-shapes-url.
     -->
     <shacl-form data-shapes="
       @prefix sh:   <http://www.w3.org/ns/shacl#> .
@@ -40,9 +35,8 @@ HTML5 web component for editing/viewing [RDF](https://www.w3.org/RDF/) data that
       form.addEventListener('change', event => {
         // check if form data validates according to the SHACL shapes
         if (event.detail?.valid) {
-          // get data graph as RDF triples and
-          // log them to the browser console
-          const triples = form.serialize()
+          // serialize the RDF graph and log it
+          const triples = form.serialize()
           console.log('entered form data', triples)
           // store the data somewhere, e.g. in a triple store
         }
@@ -51,33 +45,63 @@ HTML5 web component for editing/viewing [RDF](https://www.w3.org/RDF/) data that
   </body>
 </html>
 ```
+## Install and use in your project
+Install the package:
+```console
+npm i @ulb-darmstadt/shacl-form
+```
+This package has peer dependencies; install them in your app as well:
+```console
+npm i @ro-kit/ui-widgets jsonld leaflet leaflet-editable leaflet.fullscreen n3 rdfxml-streaming-parser shacl-engine uuid
+```
+Load the web component in your app. For a Vite/webpack-style project, import it once at startup:
+```ts
+import '@ulb-darmstadt/shacl-form'
+```
+Then use the element in your HTML:
+```html
+<shacl-form data-shapes="..."></shacl-form>
+```
+Alternatively, load the prebuilt bundle directly in a plain HTML page, as shown above:
+```html
+<script src="https://cdn.jsdelivr.net/npm/@ulb-darmstadt/shacl-form/dist/bundle.js" type="module"></script>
+```
 ### Element attributes
 Attribute | Description
 ---|---
-data-shapes | SHACL shape definitions (e.g. a turtle string) to generate the form from
-data-shapes-url | When `data-shapes` is not set, the SHACL shapes are loaded from this URL
-data-shape-subject | Optional subject (id) of the SHACL node shape to use as root for the form. If not set, the first found node shape will be used
-data-values | RDF triples (e.g. a turtle string) to use as existing data graph to fill the form
-data-values-url | When `data-values` is not set, the data graph triples are loaded from this URL
-data-values-subject | The subject (id) of the generated data. If this is not set, a blank node with a new UUID is created. If `data-values` or `data-values-url` is set, this id is also used to find the root node in the data graph to fill the form
-data-values-namespace | RDF namespace to use when generating new RDF subjects. Default is empty, so that subjects will be blank nodes.
-data-values-graph | If set, serializing the form will create a named graph with the given IRI.
-data-language | Language to use if shapes contain langStrings, e.g. in `sh:name` or `rdfs:label`. Default is [`navigator.language`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language) with fallback to [`navigator.languages`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/languages)
-data-loading | Text to display while the web component is initializing. Default: `"Loading..."`
-data&#x2011;ignore&#x2011;owl&#x2011;imports | By default, `owl:imports` URLs are fetched and the resulting RDF triples are added to the shapes graph. Setting this attribute to any value disables this feature
-data-view | When set, turns the web component into a viewer that displays the given data graph without editing functionality
-data-collapse | When set, `sh:group`s and properties with `sh:node` and `sh:maxCount` != 1 are displayed in a collapsible accordion-like widget to reduce visual complexity of the form. The collapsible element is initially shown closed, except when this attribute's value is `"open"`
-data-submit-button | [Ignored when `data-view` attribute is set] Whether to add a submit button to the form. The value of this attribute is used as the button label. `submit` events get emitted only when the form data validates
-data-generate-node-shape-reference | When generating the RDF data graph, &lt;shacl-form&gt; by default creates a triple that references the root `sh:NodeShape` of the data. Default value of this attribute is `http://purl.org/dc/terms/conformsTo`. Set this to the empty string to disable generating such a triple.
-data-show-node-ids | When this attribute is set, shacl node shapes will have their subject id shown in the form
-data-show-root-shape-label | If this is set and the root SHACL shape has `rdfs:label` or `dcterms:title` properties, &lt;shacl-form&gt; displays a heading with that value on top of the form
-data-proxy | URL of a proxy to use when fetching resources (e.g. `owl:imports`). This can help loading resources from the web that are not [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) enabled. The URL of the resource to fetch will be appended to the value of this attribute. Example value for this attribute: `http://you-proxy.org/?url=`.
-data-dense | Boolean indicating to render a compact form with small paddings and margins. Default: true
-data-hierarchy-colors | If set, a colored vertical bar is displayed on the right side of the form for each nested hierarchy level with the intention of easing orientation in complex nested forms. The value of this attribute can be a list of comma separated CSS color definitions. If no value is given, a default color palette is used.
-data-use-shadow-root | Boolean string indicating whether `<shacl-form>` renders its contents inside a shadow root. Default: 'true'. Set to 'false' to render into the light DOM.
+data-shapes | SHACL shape definitions (e.g. Turtle) used to generate the form
+data-shapes-url | When `data-shapes` is not set, load SHACL shapes from this URL
+data-shape-subject | Optional subject IRI for the root node shape. If not set, the first node shape is used
+data-values | RDF triples (e.g. Turtle) used to prefill the form
+data-values-url | When `data-values` is not set, load RDF triples from this URL
+data-values-subject | Subject (IRI or blank node id) for generated data. If not set, a blank node with a new UUID is created. If `data-values` or `data-values-url` is set, this id is used to find the root node in the data graph
+data-values-namespace | RDF namespace used when generating new RDF subjects. Default is empty, which yields blank nodes
+data-values-graph | If set, serialization creates a named graph with this IRI
+data-language | Language for `langString` values (e.g. in `sh:name` or `rdfs:label`). Default is [`navigator.language`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language) with fallback to [`navigator.languages`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/languages)
+data-loading | Text displayed while the component initializes. Default is `"Loading..."`
+data-ignore-owl-imports | By default, `owl:imports` URLs are fetched and merged into the shapes graph. Set this attribute to disable that behavior
+data-view | When set, turns the component into a viewer that displays the data graph without editing
+data-collapse | When set, `sh:group`s and properties with `sh:node` and `sh:maxCount` != 1 are rendered in a collapsible accordion. Use value `"open"` to start expanded
+data-submit-button | [Ignored when `data-view` is set] Adds a submit button. The attribute value is used as the label. `submit` events fire only when the data validates
+data-generate-node-shape-reference | When generating RDF data, adds a triple that references the root `sh:NodeShape`. Default predicate is `http://purl.org/dc/terms/conformsTo`. Set to an empty string to disable
+data-show-node-ids | Show node shape subject ids in the form
+data-show-root-shape-label | If set and the root shape has `rdfs:label` or `dcterms:title`, display that value as a heading
+data-proxy | Proxy URL used when fetching resources (e.g. `owl:imports`). The resource URL is appended to the proxy value, e.g. `http://your-proxy.org/?url=`
+data-dense | Boolean to render a compact form with smaller paddings and margins. Default is true
+data-hierarchy-colors | Comma-separated list of CSS colors for nested hierarchy bars. If unset, a default palette is used
+data-use-shadow-root | Boolean string indicating whether `<shacl-form>` renders into a shadow root. Default is `"true"`. Set to `"false"` to render into light DOM
 ### Element functions
@@ -85,101 +109,103 @@ data-use-shadow-root | Boolean string indicating whether `<shacl-form>` renders
 ```typescript
 toRDF(graph?: Store): Store
 ```
-Adds the form values as RDF triples to the given graph. If no graph object is provided, creates a new [N3 Store](https://github.com/rdfjs/N3.js#storing).
+Adds the form values as RDF triples to the given graph. If no graph is provided, creates a new [N3 Store](https://github.com/rdfjs/N3.js#storing).
 ```typescript
 serialize(format?: string, graph?: Store): string
 ```
-Serializes the given RDF graph to the given format. If no graph object is provided, this function calls toRDF() (see above) to construct the form data graph in one of the supported [output formats](#output-formats) (default is `text/turtle`).
+Serializes the given RDF graph to the given format. If no graph is provided, this calls `toRDF()` to construct the form data graph in one of the supported [output formats](#output-formats) (default is `text/turtle`).
 ```typescript
 validate(ignoreEmptyValues: boolean): Promise<boolean>
 ```
-Validates the form data against the SHACL shapes graph and displays validation results as icons next to the respective input fields. If `ignoreEmptyValues` is true, empty form fields will not be marked as invalid. This function is also internally called on `change` and `submit` events.
+Validates form data against the SHACL shapes graph and displays validation results as icons next to the respective input fields. If `ignoreEmptyValues` is true, empty fields will not be marked invalid. This function is also invoked on `change` and `submit` events.
 ```typescript
 registerPlugin(plugin: Plugin)
 ```
-Register a [plugin](./src/plugin.ts) to customize editing/viewing certain property values. Plugins handle specific RDF predicates or `xsd:datatype`s or both. Example: [Leaflet](./src/plugins/leaflet.ts)
+Registers a [plugin](./src/plugin.ts) to customize editing/viewing of certain values. Plugins handle specific RDF predicates, `xsd:datatype`s, or both. Example: [Leaflet](./src/plugins/leaflet.ts)
 ```typescript
 setTheme(theme: Theme)
 ```
-Set a design theme to use for rendering. See section [Theming](#Theming).
+Sets the design theme used for rendering. See [Theming](#theming).
 ```typescript
 setClassInstanceProvider((className: string) => Promise<string>)
 ```
-Sets a callback function that is invoked when a SHACL property has an `sh:class` definition to retrieve class instances. See [below](#classInstanceProvider) for more information.
+Sets a callback that is invoked when a SHACL property has an `sh:class` definition to retrieve class instances. See [below](#classInstanceProvider) for details.
 ```typescript
 setResourceLinkProvider(provider: ResourceLinkProvider)
 ```
-Registers a callback provider that supplies existing resources for linking. The provider is used to list resources that conform to the node shapes of a property and to load RDF data for selected resources. See [below](#resourceLinkProvider) for details.
+Registers a callback provider that supplies existing resources for linking. The provider lists resources that conform to a node shape and loads RDF data for selected resources. See [below](#resourcelinkprovider).
 ## Features
 ### Validation
-In edit mode, `<shacl-form>` validates the constructed data graph using the library [shacl-engine](https://github.com/rdf-ext/shacl-engine) and displays validation results as icons next to the respective form fields.
+In edit mode, `<shacl-form>` validates the constructed data graph using [shacl-engine](https://github.com/rdf-ext/shacl-engine) and displays validation results as icons next to the relevant fields.
 ### Data graph binding
-`<shacl-form>` requires only a shapes graph as input via the attribute `data-shapes` (or `data-shapes-url`) to generate an empty form and create new RDF data from the form input fields. Using the attributes `data-values` (or `data-values-url`) and `data-values-subject`, you can also bind an existing data graph to the form. The given data graph is then used to fill the form input fields.
+`<shacl-form>` requires only a shapes graph as input via `data-shapes` (or `data-shapes-url`) to generate an empty form and create new RDF data from user input. Using `data-values` (or `data-values-url`) and `data-values-subject`, you can also bind an existing data graph to the form and prefill the fields.
 ### Viewer mode
-`<shacl-form>` not only is an RDF data editor, but can also be used as a viewer by setting attribute `data-view` and binding both, a shapes and a data graph. See the [demo](https://ulb-darmstadt.github.io/shacl-form/#viewer-mode) for an example.
+`<shacl-form>` is both an editor and a viewer. Set `data-view` and bind a shapes graph and a data graph to render a read-only view. See the [demo](https://ulb-darmstadt.github.io/shacl-form/#viewer-mode).
 ### Providing additional data to the shapes graph
-Apart from setting the element attributes `data-shapes` or `data-shapes-url`, there are two ways of adding RDF data to the shapes graph:
-1. While parsing the triples of the shapes graph, any encountered `owl:imports` predicate that has a valid HTTP URL is fetched with the HTTP Accept header set to all of the [supported](#formats) MIME types. A successful response is parsed and added to a named graph. This graph is scoped (i.e. available) only to the node where the `owl:import` statement is defined on and all its sub nodes.
-    The [example shapes graph](https://ulb-darmstadt.github.io/shacl-form/#example) contains the following triples:
-    ```
-    example:Attribution
-      sh:property [
-        owl:imports <https://w3id.org/nfdi4ing/metadata4ing/> ;
-        sh:name      "Role" ;
-        sh:path      dcat:hadRole ;
-        sh:class     prov:Role ;
-      ] .
-    ```
-    In this case, the URL references an ontology which among other things defines instances of class `prov:Role` that are then used to populate the "Role" dropdown in the form. The imported ontology is available only for rendering and validating this specific property.
-2. <a id="classInstanceProvider"></a>The `<shacl-form>` element has a function `setClassInstanceProvider((className: string) => Promise<string>)` that registers a callback function which is invoked when a SHACL property has
-an `sh:class` predicate. The expected return value is a (promise of a) string (e.g. in format `text/turtle`) that contains RDF class instance definitions of the given class.
-    In [this example](https://ulb-darmstadt.github.io/shacl-form/#example), the code:
-    ```typescript
-    form.setClassInstanceProvider((clazz) => {
-      if (clazz === 'http://example.org/Material') {
-        return `
-          <http://example.org/steel>   a <http://example.org/Material>; <http://www.w3.org/2000/01/rdf-schema#label> "Steel".
-          <http://example.org/wood>    a <http://example.org/Material>; <http://www.w3.org/2000/01/rdf-schema#label> "Wood".
-          <http://example.org/alloy>   a <http://example.org/Material>; <http://www.w3.org/2000/01/rdf-schema#label> "Alloy".
-          <http://example.org/plaster> a <http://example.org/Material>; <http://www.w3.org/2000/01/rdf-schema#label> "Plaster".
-        `
-      }}
-    )
-    ```
-    returns instances of the class `http://example.org/Material` that are then used to populate the "Artwork material" dropdown in the form.
+Besides `data-shapes` and `data-shapes-url`, there are two ways to add RDF data to the shapes graph:
+1. While parsing the shapes graph, any `owl:imports` predicate with a valid HTTP URL is fetched. The response is parsed (using one of the [supported](#formats) MIME types) and added to a named graph. This graph is scoped to the node where the `owl:import` is defined and its sub nodes.
+   The [example shapes graph](https://ulb-darmstadt.github.io/shacl-form/#example) contains the following triples:
+   ```
+   example:Attribution
+     sh:property [
+       owl:imports <https://w3id.org/nfdi4ing/metadata4ing/> ;
+       sh:name      "Role" ;
+       sh:path      dcat:hadRole ;
+       sh:class     prov:Role ;
+     ] .
+   ```
-    A more realistic use case of this feature is calling some API endpoint to fetch class instance definitions from existing ontologies.
+   In this case, the URL references an ontology that defines instances of `prov:Role`. These instances populate the "Role" dropdown. The imported ontology is available only for rendering and validating this specific property.
+2. <a id="classInstanceProvider"></a>The `<shacl-form>` element exposes `setClassInstanceProvider((className: string) => Promise<string>)`, a callback invoked when a property has `sh:class`. The return value is a string (e.g. `text/turtle`) containing instance definitions of the given class.
+   In [this example](https://ulb-darmstadt.github.io/shacl-form/#example), the code:
+   ```typescript
+   form.setClassInstanceProvider((clazz) => {
+     if (clazz === 'http://example.org/Material') {
+       return `
+         <http://example.org/steel>   a <http://example.org/Material>; <http://www.w3.org/2000/01/rdf-schema#label> "Steel".
+         <http://example.org/wood>    a <http://example.org/Material>; <http://www.w3.org/2000/01/rdf-schema#label> "Wood".
+         <http://example.org/alloy>   a <http://example.org/Material>; <http://www.w3.org/2000/01/rdf-schema#label> "Alloy".
+         <http://example.org/plaster> a <http://example.org/Material>; <http://www.w3.org/2000/01/rdf-schema#label> "Plaster".
+       `
+     }
+   })
+   ```
+   returns instances of `http://example.org/Material`, which populate the "Artwork material" dropdown.
+   A more realistic use case is calling an API endpoint to fetch class instances from existing ontologies.
 ### Use of SHACL sh:class
-In case a property shape has a `sh:class`, all available graphs are scanned for instances of the given class to let the user choose from. `rdfs:subClassOf` is also considered when building the list of class instances.
+When a property shape has an `sh:class`, all available graphs are scanned for instances of that class so users can choose from them. `rdfs:subClassOf` is also considered when building the list of class instances.
 `shacl-form` also supports class instance hierarchies modelled with `skos:broader` and/or `skos:narrower`. This is illustrated by the "Subject classification" property in the [example](https://ulb-darmstadt.github.io/shacl-form/#example).
 ### SHACL constraints sh:or and sh:xone
-`<shacl-form>` supports using [sh:or](https://www.w3.org/TR/shacl/#OrConstraintComponent) and [sh:xone](https://www.w3.org/TR/shacl/#XoneConstraintComponent) to let users select between different options on nodes or properties.
-The [example shapes graph](https://ulb-darmstadt.github.io/shacl-form/#example) has the following triples:
+`<shacl-form>` supports [sh:or](https://www.w3.org/TR/shacl/#OrConstraintComponent) and [sh:xone](https://www.w3.org/TR/shacl/#XoneConstraintComponent) to let users choose between different options on nodes or properties. The [example shapes graph](https://ulb-darmstadt.github.io/shacl-form/#example) includes:
 ```
 example:Attribution
   a sh:NodeShape ;
@@ -193,34 +219,34 @@ example:Attribution
     )
   ] .
 ```
-When adding a new attribution, `<shacl-form>` renders a dropdown to let the user select between the two options Person/Organisation. After selecting one of the options, the dropdown is replaced by the input fields of the selected node shape.
-When binding an existing data graph to the form, the constraint is tried to be resolved depending on the respective data value:
+When adding a new attribution, `<shacl-form>` renders a dropdown to select Person/Organisation. After selection, the dropdown is replaced by the input fields of the chosen node shape.
+When binding an existing data graph to the form, the constraint is resolved based on the data value:
 - For RDF literals, an `sh:or` option with a matching `sh:datatype` is chosen
-- For blank nodes or named nodes, the `rdf:type` of the value is tried to be matched with a node shape having a corresponding `sh:targetClass` or with a property shape having a corresponding `sh:class`. If there is no `rdf:type` but a `sh:nodeKind` of `sh:IRI`, the id of the the node is used as the value.
+- For blank nodes or named nodes, the `rdf:type` is matched with a node shape having a corresponding `sh:targetClass` or with a property shape having a corresponding `sh:class`. If there is no `rdf:type` but a `sh:nodeKind` of `sh:IRI`, the node id is used as the value
 ### Linking existing data
-In case a node shape has a `sh:targetClass` and any graph, i.e.
+When a node shape has a `sh:targetClass` and any graph contains instances of that class, those instances can be linked in the respective SHACL property. The generated data graph will then contain only a reference to the instance, not its full triples.
+Graphs considered are:
 - the shapes graph
 - the data graph
-- any graph loaded by `owl:imports`
+- any graph loaded via `owl:imports`
 - triples provided by [classInstanceProvider](#classInstanceProvider)
-contains instances of that class, those can be linked in the respective SHACL property. The generated data graph will then just contain a reference to the instance, but not the triples that the instance consists of.
 <a id="resourceLinkProvider"></a>
-If your graphs only contain the resource identifiers (IRIs) and not the full triples for linked resources, you can use `setResourceLinkProvider` to supply them on demand. The `ResourceLinkProvider` lets you:
+If your graphs only contain resource identifiers (IRIs) and not the full triples for linked resources, you can use `setResourceLinkProvider` to supply them on demand. The `ResourceLinkProvider` lets you:
 * List resources that conform to a node shape so they can appear in the "Link existing ..." dialog.
-* Load RDF data for selected resource IRIs so the `shacl-form` can resolve, display and validate linked resources.
+* Load RDF data for selected resource IRIs so the `shacl-form` can resolve, display, and validate linked resources.
-The provider supports eager loading (resolve resources during initialization) or lazy loading (resolve when the user opens the link dialog).
+The provider supports eager loading (resolve resources during initialization) or lazy loading (resolve when the user opens the link dialog). See [here](https://github.com/ULB-Darmstadt/rdf-store/blob/main/frontend/src/editor.ts#L10) for an example implementation.
 ### SHACL shape inheritance
-SHACL defines two ways of inheriting shapes: [sh:and](https://www.w3.org/TR/shacl/#AndConstraintComponent)
-and [sh:node](https://www.w3.org/TR/shacl/#NodeConstraintComponent). `<shacl-form>` supports both. In [this example](https://ulb-darmstadt.github.io/shacl-form/#example), node shape `example:ArchitectureModelDataset` extends `example:Dataset` by defining the following RDF triple:
+SHACL defines two ways of inheriting shapes: [sh:and](https://www.w3.org/TR/shacl/#AndConstraintComponent) and [sh:node](https://www.w3.org/TR/shacl/#NodeConstraintComponent). `<shacl-form>` supports both. In [this example](https://ulb-darmstadt.github.io/shacl-form/#example), node shape `example:ArchitectureModelDataset` extends `example:Dataset` by defining:
 ```
 example:ArchitectureModelDataset sh:node example:Dataset .
@@ -230,42 +256,94 @@ Properties of inherited shapes are displayed first.
 ### Plugins
-Plugins can modify rendering of the form and add functionality to edit and view certain RDF datatypes or predicates (or a combination of both). As an example, the JavaScript of [this page](https://ulb-darmstadt.github.io/shacl-form/#example) contains the following code:
+Plugins can modify rendering and add edit/view functionality for specific RDF datatypes or predicates (or both). For example, the JavaScript on [this page](https://ulb-darmstadt.github.io/shacl-form/#example) includes:
 ```typescript
 import { LeafletPlugin } from '@ulb-darmstadt/shacl-form/plugins/leaflet.js'
 const form = document.getElementById("shacl-form")
 form.registerPlugin(new LeafletPlugin({ datatype: 'http://www.opengis.net/ont/geosparql#wktLiteral' }))
 ```
-In effect, whenever a SHACL property has an `sh:datatype` of `http://www.opengis.net/ont/geosparql#wktLiteral`, the plugin is called to create the editor and/or viewer HTML elements. This specific plugin uses [Leaflet](https://leafletjs.com/) to edit or view geometry in format [well known text](http://giswiki.org/wiki/Well_Known_Text) on a map.
-Custom plugins can be built by extending class [Plugin](https://github.com/ULB-Darmstadt/shacl-form/blob/main/src/plugin.ts#L40).
+When a SHACL property has datatype `http://www.opengis.net/ont/geosparql#wktLiteral`, the plugin renders the editor/viewer elements. This plugin uses [Leaflet](https://leafletjs.com/) to edit or view geometry in [well known text](http://giswiki.org/wiki/Well_Known_Text) on a map.
+Custom plugins can be built by extending [Plugin](https://github.com/ULB-Darmstadt/shacl-form/blob/main/src/plugin.ts#L40).
 ### Property grouping and collapsing
 Properties can be grouped using [sh:group](https://www.w3.org/TR/shacl/#group) in the shapes graph. [This example](https://ulb-darmstadt.github.io/shacl-form/#example) defines a group "Physical properties" and assigns certain properties to it.
-When the element attribute `data-collapse` is set, `<shacl-form>` creates an accordion-like widget that toggles the visibility of grouped properties in order to reduce the visual complexity of the form. If the grouped properties should initially be shown, set `data-collapse="open"`.
+When `data-collapse` is set, `<shacl-form>` creates an accordion-like widget that toggles grouped properties to reduce visual complexity. If the grouped properties should start open, set `data-collapse="open"`.
-Apart from grouped properties, all properties having an `sh:node` predicate and `sh:maxCount` != 1 are collapsed.
+In addition, all properties with `sh:node` and `sh:maxCount` != 1 are collapsed.
 ### Supported RDF formats
+<a id="formats"></a>
 #### Input formats
-* text/turtle, application/n-triples, application/n-quads, application/trig using [N3 parser](https://github.com/rdfjs/N3.js?tab=readme-ov-file#parsing)
-* application/ld+json using [jsonld](https://github.com/digitalbazaar/jsonld.js)
-* application/rdf+xml using [rdfxml-streaming-parser](https://github.com/rdfjs/rdfxml-streaming-parser.js)
+- text/turtle, application/n-triples, application/n-quads, application/trig using the [N3 parser](https://github.com/rdfjs/N3.js?tab=readme-ov-file#parsing)
+- application/ld+json using [jsonld](https://github.com/digitalbazaar/jsonld.js)
+- application/rdf+xml using [rdfxml-streaming-parser](https://github.com/rdfjs/rdfxml-streaming-parser.js)
 #### Output formats
 <a id="output-formats"></a>
-* text/turtle, application/n-triples, application/n-quads, application/trig using [N3 writer](https://github.com/rdfjs/N3.js?tab=readme-ov-file#writing)
-* application/ld+json using [jsonld](https://github.com/digitalbazaar/jsonld.js)
+- text/turtle, application/n-triples, application/n-quads, application/trig using the [N3 writer](https://github.com/rdfjs/N3.js?tab=readme-ov-file#writing)
+- application/ld+json using [jsonld](https://github.com/digitalbazaar/jsonld.js)
+### Theming
+`<shacl-form>` has a built-in abstraction layer for theming the form controls. To use another theme (e.g. Bootstrap or Material Design), extend [Theme](./src/theme.ts) and call `setTheme()` on the element.
+If you only want to restyle the existing widgets (without re-implementing internal behavior), you can use CSS in two ways:
+1) Render into light DOM for global CSS:
+```html
+<shacl-form data-use-shadow-root="false"></shacl-form>
+```
+2) Use CSS variables and parts (works with Shadow DOM too). The following CSS variables are supported:
+```css
+shacl-form {
+  --shacl-font-family: system-ui, sans-serif;
+  --shacl-font-size: 14px;
+  --shacl-text-color: #333;
+  --shacl-muted-color: #555;
+  --shacl-border-color: #ddd;
+  --shacl-bg: #fff;
+  --shacl-row-alt-bg: #f8f8f8;
+  --shacl-error-color: #c00;
+  --shacl-label-width: 10em;
+}
+```
+And these parts are exposed for styling:
+```css
+shacl-form::part(form) { padding: 8px; }
+shacl-form::part(field) { gap: 6px; }
+shacl-form::part(label) { font-weight: 600; }
+shacl-form::part(editor) { border-radius: 6px; }
+shacl-form::part(button) { min-height: 32px; }
+shacl-form::part(primary) { font-weight: 700; }
+shacl-form::part(add-button) { }
+shacl-form::part(remove-button) { }
+shacl-form::part(link-button) { }
+shacl-form::part(submit-button) { }
+```
+Available parts:
+`form`, `node`, `linked-node`, `node-title`, `group`, `group-title`, `collapsible`, `property`, `property-instance`, `field`, `label`, `editor`, `lang-chooser`, `constraint`, `constraint-editor`, `add-controls`, `remove-controls`, `add-button`, `remove-button`, `link-button`, `submit-button`, `button`, `primary`.
+Note: the [default widgets](https://gitlab.ulb.tu-darmstadt.de/rokit/ui-widgets) are provided by ULB Darmstadt. Those components expose their own `part` names; you can style them via `::part(...)` selectors on the respective elements. See the [README](https://gitlab.ulb.tu-darmstadt.de/rokit/ui-widgets) for documentation.
 ### Use with Solid Pods
-`<shacl-form>` can easily be integrated with [Solid Pods](https://solidproject.org/about). The output of `toRDF()` being a RDF/JS N3 Store, as explained [above](#toRDF), it can be presented to `solid-client`s `fromRdfJsDataset()` function, which converts the RDF graph into a Solid Dataset. The following example, based on Inrupt's basic [Solid Pod example](https://docs.inrupt.com/sdk/javascript-sdk/tutorial) shows how to merge data from a `<shacl-form>` with a Solid data resource at `readingListDataResourceURI`:
+`<shacl-form>` can be integrated with [Solid Pods](https://solidproject.org/about). Because `toRDF()` returns an RDF/JS N3 Store (see [above](#toRDF)), it can be passed to the Solid client `fromRdfJsDataset()` function to convert it into a Solid Dataset. The example below (based on Inrupt's [Solid Pod tutorial](https://docs.inrupt.com/sdk/javascript-sdk/tutorial)) shows how to merge data from a `<shacl-form>` with a Solid data resource at `readingListDataResourceURI`:
 ```js
-  // Authentication is assumed, resulting in a fetch able to read and write into the Pod
+  // Authentication is assumed, resulting in a fetch function able to read and write into the Pod
   try {
     // Get data out of the shacl-form
     const form = document.querySelector('shacl-form')
@@ -296,7 +374,3 @@ Apart from grouped properties, all properties having an `sh:node` predicate and
     console.error(`Storing SHACL data from Form failed with error ${err}!`)
   }
 ```
-### Theming
-`<shacl-form>` has a built-in abstraction layer for theming, i.e. the look and feel of the form elements. If you would like to employ a different theme like e.g. `bootstrap` or `material design`, then extend class [Theme](./src/theme.ts) and call function `setTheme()` on the `<shacl-form>` element.