Add bulk changes to documentation; still a work in progress, with TOD…

…Os annotated

docs/.vitepress/config.mjs

@@ -3,7 +3,7 @@ import { defineConfig } from 'vitepress'
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
   base: "/shacl-vue/docs/",
-  title: "shacl-vue",
+  title: "shacl-vue (alpha)",
   description: "Automatic generation of user interfaces from SHACL",
   head: [['link', { rel: 'icon', href: '/shacl-vue/docs/favicon.ico' }]],
   themeConfig: {
@@ -17,24 +17,34 @@ export default defineConfig({
     sidebar: [
       {
         items: [
-          { text: 'Overview', link: '/get-started' },
+          { text: 'Get started', link: '/get-started' },
         ]
       },
       {
         text: 'App design',
         items: [
           { text: 'The big picture', link: '/app-design' },
+          { text: 'Core concepts', link: '/core-concepts' },
+          { text: 'Code layout', link: '/code-layout' },
+          { text: 'Component hierarchy', link: '/component-hierarchy' },
+          { text: 'The editor component', link: '/editor-component' },
+          { text: 'Editor component matching', link: '/component-matching' },
         ]
       },
       {
         text: 'Setup and deployment',
         items: [
+          { text: 'Application inputs', link: '/app-inputs' },
         ]
       },
       {
-        text: 'API Docs',
+        text: 'API Docs (TODO)',
         items: [
         ]
+      },
+      {
+        text: 'Contributing',
+        link: '/contributing'
       }
     ],
 

docs/app-inputs.md

@@ -0,0 +1,128 @@
+---
+layout: doc
+---
+
+# Application inputs
+
+## Required inputs
+
+`shacl-vue` needs 4 inputs to function as expected:
+
+1. A SHACL shapes graph, ideally annotated with the details highlighted in the [Core concepts section](./core-concepts#shacl)
+2. A class hierarchy of the classes mentioned in the shapes graph, detailing subclass relationships.
+3. A data graph with existing RDF data that could be used or linked in the generated forms.
+4. A set of matchable editor components that will be self-selected and rendered in a form, based on the SHACL shapes.
+
+The current application sources already contain a sample [SHACL shapes graph](https://github.com/psychoinformatics-de/shacl-vue/blob/main/src/assets/shapesgraph.ttl), a [class hierarchy](https://github.com/psychoinformatics-de/shacl-vue/blob/main/src/assets/class_hierarchy.ttl), a [data graph](https://github.com/psychoinformatics-de/shacl-vue/blob/main/src/assets/distribution-penguins-mini.ttl), and a [set of matchable components](https://github.com/psychoinformatics-de/shacl-vue/tree/main/src/components). These all underlie the demo `shacl-vue` instance.
+
+However, these can all be replaced or amended in order to customize your application instance.
+
+## Preparing the shapes graph
+
+A SHACL shapes graph (with its `NodeShape`s, `PropertyShape`s, and UI annotations) is the core driver of a `shacl-vue` application. These shapes can be edited directly as SHACL, for example using [TTL syntax](https://www.w3.org/TR/turtle/) and provided as a text file `myshapesgraph.ttl`.
+
+### Schema authoring
+
+Considering SHACLs interoperability with the wider world of linked data standards, however, it could be likely that your schema is rather edited in a different modeling language and then exported to SHACL. One such example, [LinkML](https://linkml.io/), has been used extensively as the source for SHACL schemas for `shacl-vue`. LinkML schemas can be authored in YAML and exported to a variety of RDF formats, including SHACL. For some example schemas, have a look at [DataLad Concepts](https://concepts.datalad.org/), in particular the [Scientific Data Distribution](https://concepts.datalad.org/s/sdd/unreleased/) schema, which is the source for the SHACL shapes graph used in the `shacl-vue` demo instance.
+
+### Adding UI annotations
+
+LinkML generates a SHACL shapes graph from a LinkML schema using its [SHACL generator](https://linkml.io/linkml/generators/shacl.html). By default, the shapes only contain a minimum set of constraints based on the generator's slim translation of LinkML classes, slots, etc, into SHACL shapes and associated constraints. UI annotations, specifically the ones highlighted in the [Core concepts section](./core-concepts#shacl), need to be added in order to let `shacl-vue` generate a form that is intuitive and user-friendly. Below is an example of how a new schema can be set up to firstly inherit from an existing schema, and secondly add UI-specific annotations:
+
+```yaml
+classes:
+
+  ScientificDataDistribution:
+    class_uri: dlsddui:ScientificDataDistribution
+    is_a: Distribution
+    slot_usage:
+      name:
+        title: Name
+        annotations:
+          sh:group: dlsddui:BasicPropertyGroup
+          sh:order: 0
+      title:
+        title: Title
+        annotations:
+          sh:group: dlsddui:BasicPropertyGroup
+          sh:order: 1
+      description:
+        title: Description
+        annotations:
+          sh:group: dlsddui:BasicPropertyGroup
+          sh:order: 2
+```
+
+Take note that:
+- A new class `ScientificDataDistribution` is created and it inherits from the actual class for which we want to generate SHACL (`is_a: Distribution`).
+- Each slot that we want to annotate gets:
+   - a `title` field, which serves as the user-friendly name for the field in a generated form, and in the absence of which the SHACL generator will use the slot name
+   - an `annotations` field, with `sh:group` and `sh:order` which determine in which thematic group a field is displayed in the form, and in which order
+- While field `description`s are not included in this example since they already exist on the slots of the base class (`Distribution`), they are absolutely encouraged to provide even more useful information to a user
+
+Other annotations are of course possible, and would be listed under the `annotations` field, but currently those highlighted in this example are the essential ones that allow `shacl-vue` to render user-friendly forms.
+
+### Creating `PropertyGroup`s
+
+While specific class slots being annotated with an `sh:group` constitutes one part of intuitive grouping of form fields, the other necessary part is actually defining these groups. For this, an additional graph is necessary. Here is an example of a single `PropertyGroup` specification:
+
+```rdf
+dlsddui:BasicPropertyGroup a sh:PropertyGroup ;
+	rdfs:label "Basic" ;
+	sh:order "0"^^xsd:decimal ;
+    rdfs:comment "Basic properties of the dataset distribution" .
+```
+
+Again, for ease of authoring, this can also be written in YAML and then converted to SHACL. Here is the same example in YAML:
+
+```yaml
+property_groups:
+  - id: dlsddui:BasicPropertyGroup 
+    label: Basic
+    order: 0
+    description: >-
+      Basic properties of the dataset distribution
+```
+
+This is data that can be validated against a LinkML schema and converted to the RDF shown above. Such a schema was developed for this exact purpose, and is available at [shacl-vue/tools/property_group_schema.yaml](https://github.com/psychoinformatics-de/shacl-vue/blob/main/tools/property_group_schema.yaml).
+
+
+### Exporting SHACL
+
+Now that we have an annotated LinkML schema as well as associated property groups, we can generate the SHACL graph that feeds the `shacl-vue` application. A Python script was developed to simplify this process. It is available at [shacl-vue/tools/gen_shacl_ui.py](https://github.com/psychoinformatics-de/shacl-vue/blob/main/tools/gen_shacl_ui.py) and can be used as follows via the command line:
+
+```
+cd shacl-vue
+python tools/gen_shacl_ui.py <path/to/linkml/schema> <path/to/property/groups/data>
+```
+
+As an example, for `shacl-vue`'s demo instance the SHACL shapes graph at [shacl-vue/src/assets/shapesgraph.ttl](https://github.com/psychoinformatics-de/shacl-vue/blob/main/src/assets/shapesgraph.ttl) was generated with the following inputs:
+- schema: https://github.com/jsheunis/datalad-concepts/blob/annotations-etc/src/sddui/unreleased.yaml
+- property groups: https://github.com/psychoinformatics-de/shacl-vue/blob/main/src/assets/sddui-shacl-groups.yaml
+
+
+## Creating the class hierarchy
+
+As with the schema and SHACL generation above, LinkML and helper scripts can be used to generate the required `shacl-vue` inut. Here, LinkML's OWL generator is used, and the output is then filtered to only include all triples in the graph where the predicate equals `rdfs:subClassOf`. This is linked-data speak for saying: lets only extract all information about which class is a subclass of which other class, which allows us to put together a hierarchy of classes.
+
+A Python script for this process is available at [shacl-vue/tools/gen_owl_minimal.py](https://github.com/psychoinformatics-de/shacl-vue/blob/main/tools/gen_owl_minimal.py) and can be used as follows via the command line:
+
+```
+cd shacl-vue
+python tools/gen_owl_minimal.py <path/to/linkml/schema>
+```
+
+
+## Preparing the data graph
+
+When users complete forms, they often do so for data that exists in a wider context. Imagine a consortium of research groups, all collaborating on projects that belong to a specific, coherent theme. It is conceivable that participating researchers would collect data together, write academic papers together, share funding from the same sources, and more. If they then complete forms in order to describe their collected data, they might want to reference the same authors, the same funding sources, etc. No use in entering the same data twice. For this reason, it is useful to make existing data using existing namespaces available to the `shacl-vue` instance. This can be done by providing a file with RDF data, such as the demo example at: https://github.com/psychoinformatics-de/shacl-vue/blob/main/src/assets/distribution-penguins-mini.ttl.
+
+## Adding custom components
+
+While `shacl-vue` ships with a set of default editor components that cover most standard use cases of form entry, developers are free to add their own custom components.
+
+**to be continued...**
+
+
+
+

docs/code-layout.md

@@ -0,0 +1,36 @@
+---
+layout: doc
+---
+
+# Code Layout
+
+For developers/controbutors, the noteworthy parts of this code repository are shown below:
+
+```
+.
+├── docs
+├── node_modules
+├── public
+├── src
+│   ├── assets
+│   ├── components
+│   ├── composables
+│   ├── modules
+│   └── plugins
+└── tools
+```
+
+- **docs**: this directory contains the sources for these documentation pages
+- **public**: this directory should contain any assets that are to be located in the root of the served address of the built application
+- **src**: this is the source code of the `shacl-vue` application
+   - *assets* contain styles, images, fonts, and currently also the shapes graph (`shapesgraph.ttl`), data graph (`distribution-penguins-mini.ttl`), and class hierarchy information (`class_hierarchy.ttl`) that are all loaded into the application on startup.
+   - *components* contain all VueJS components used by the application. These include all internal components that support the application's built-in functionality, as well as all custom editors that together constitute the application's library of matchable components for form fields.
+   - *composables* contain modules with general functionality that can be used across components, specifically:
+      - `base.js` for common functionality of any custom input component, which all new input components should import
+      - `classdata.js` for managing class hierarchy information
+      - `formdata.js` for managing data entered into form fields
+      - `graphdata.js` for managing RDF data that have been taken from forms and saved into a graph store
+      - `refregister.js` which provides a means to track references to a parent component's children when validating a form
+      - `rules.js` for common functionality used in input field validation
+      - `shapedata.js` for managing the source shapes graph
+   - *modules* and *plugins* have further modules with helper functionality or functionality that extends the application

docs/component-hierarchy.md

@@ -0,0 +1,9 @@
+---
+layout: doc
+---
+
+# Component Hierarchy
+
+::: info
+TODO
+:::

docs/component-matching.md

@@ -0,0 +1,9 @@
+---
+layout: doc
+---
+
+# Editor Component Matching
+
+::: info
+TODO
+:::

docs/contributing.md

@@ -0,0 +1,7 @@
+---
+layout: doc
+---
+
+# Contributing
+
+Development is ongoing and contributions are very welcome. Coordination happens via the source code repository at https://github.com/psychoinformatics-de/shacl-vue. Please have a look at the [open issues](https://github.com/psychoinformatics-de/shacl-vue/issues) to see if your question has already been brought up before. If not, please create a new issue for discussion.

docs/core-concepts.md

@@ -0,0 +1,60 @@
+---
+layout: doc
+---
+
+# Core Concepts
+
+`shacl-vue`'s functionality rests on several core concepts from its constituent technologies: SHACL, VueJS, and RDF-Ext.
+
+## SHACL
+
+::: tip
+For a thorough understanding of SHACL, please refer to https://www.w3.org/TR/shacl/
+:::
+
+The main concepts used from SHACL include the two types of shapes:
+
+> - shapes about the focus node itself, called node shapes [`sh:NodeShape`]
+> - shapes about the values of a particular property or path for the focus node, called property shapes [`sh:PropertyShape`]
+
+In terms of user interfaces, a `NodeShape` would specify the schema for a complete form, while related `PropertyShape`s would specify the schemas for individual fields in a form. Knowing the details of these schemas, i.e. knowing how they validate graph data, allows us to generate appropriate UI components for capturing valid data.
+
+The details of these concepts include:
+- [targets](https://www.w3.org/TR/shacl/#targets) specified for a `NodeShape` or a `PropertyShape` which can indicate e.g. which class a set of data would have to be validated against
+- [`nodeKind`](https://www.w3.org/TR/shacl/#NodeKindConstraintComponent), which specifies which kind of RDF node the field would constitute, such as `sh:IRI` or `sh:BlankNode`.
+- [`datatype`](https://www.w3.org/TR/shacl/#DatatypeConstraintComponent), which specifies what data type a field should have, e.g. `string` or `datetime`
+
+In addition to specifications that can be used to render to correct field for a `PropertyShape` and provide the associated validation rules, a SHACL shapes graph can also contain information to construct the layout of a form and make it more user-friendly. These are known as [non-validating property shape characteristics](https://www.w3.org/TR/shacl/#nonValidation):
+- [`sh:name` and `sh:description`](https://www.w3.org/TR/shacl/#name) can be included to make a field more intuitive to a user
+- [`sh:order`](https://www.w3.org/TR/shacl/#order) can be used to provide order to the fields of a form
+- [`sh:group`](https://www.w3.org/TR/shacl/#group) specified on a `PropertyShape` can tell the form builder which `sh:PropertyGroup` a field belongs to in terms of a grouping of themes or subsections in a form
+
+Together, all of these concepts can be put together into a shapes graph in order to provide a full specification of a form and its fields, readily interpretable by a tool such as `shacl-vue`, and ready to validate data on entry.
+
+
+::: info
+Currently, `shacl-vue` does not yet support the full SHACL specification, only the basics. A complete list of supported SHACL features will follow. See https://www.w3.org/TR/shacl/#core-components for a complete list of SHACL's constraint components.
+:::
+
+## VueJS
+
+`shacl-vue` is implemented using VueJS 3, specifically the [Composition API](https://vuejs.org/guide/extras/composition-api-faq.html).
+
+The application makes extensive use of:
+
+- [Vue Components](https://vuejs.org/guide/essentials/component-basics.html) to create standalone functional units that specify their own look and feel (`<template>`), their logic and state management code (`<scritp setup>`), additional JavaScript code (`<script>`), and any optional local styling (`<style scoped>`). These components are the main driver behind `shacl-vue`'s ability to render different forms and fields based on the specifications in a SHACL schema.
+- [Lifecycle hooks](https://vuejs.org/guide/essentials/lifecycle) to run tasks during a component's life cycle, e.g. after creation or on mounting.
+- [Provide / Inject](https://vuejs.org/guide/components/provide-inject.html) to share states between parent and child components
+- [Composables](https://vuejs.org/guide/reusability/composables.html) to manage generalizable and reusable code across components.
+- [Vuetify](https://vuetifyjs.com/en/) as a framework for existing UI components. Of note is the generic [`v-input`](https://vuetifyjs.com/en/components/inputs/#inputs) which acts as a wrapper for `shacl-vue` input components in order to standardize the API.
+
+## RDF-Ext
+
+[RDF-Ext](https://github.com/rdf-ext/rdf-ext) is a
+
+> JavaScript library that extends the [RDF/JS specs](https://rdf.js.org/) to handle RDF data in a developer-friendly way.
+
+`shacl-vue` mainly uses RDF-Ext to:
+- read RDF data into the application's graph store, which is managed as a VueJS-reactive [`rdf.dataset()`](https://rdf.js.org/dataset-spec/)
+- add quads to the graphh store (`rdf.dataset().add(quad)`)
+- traverse a graph in order to find specific nodes, using [`grapoi`](https://github.com/rdf-ext/grapoi)

docs/editor-component.md

@@ -0,0 +1,9 @@
+---
+layout: doc
+---
+
+# The Editor Component
+
+::: info
+TODO
+:::