update component docs

src/docs/component/advanced-usage.md

@@ -30,27 +30,29 @@ import DescriboCrateBuilder from ...
 
 
 const describo = ref()
-
 // console.log(describo.value)
-// {
-//    cm: function(),
-//    refresh: function(),
-//    setCurrentEntity: function({ id }),
-//    setTab: function(tabName)
-// }
 ```
 
 If you connect to the component via a reference, you will get access to an object with the following
 properties:
 
--   cm: the internal CrateManager instance that the component uses to manipulate the data;
--   pm: the internal ProfileManager instance; makes handling profiles/schema.org classes easy;
--   refresh: a method to tell the current entity to refresh its display;
--   setCurrentEntity({ id }): a method to set the enity to display;
--   setTab(tabName): a method to display the selected tab.
+-   `cm`: the internal CrateManager instance that the component uses to manipulate the data;
+-   `pm`: the internal ProfileManager instance; makes handling profiles/schema.org classes easy;
+-   `state`: the internal state manager instance with controls to navigate back and forth and patch
+    the current state;
+-   `refresh`: a method to tell the current entity to refresh its display;
+-   `setCurrentEntity({ id })`: a method to set the enity to display;
+-   `setTab(tabName)`: a method to display the selected tab;
+-   `toggleReverseLinkBrowser`: a method to open / close the reverse link browser.
 
 Following are some examples of how you can use these methods.
 
+## jsdoc docs
+
+You should also consult the documentation for Crate Manager (cm), Profile Manager (pm) and Editor
+State (state) @
+[https://describo.github.io/crate-builder-component/](https://describo.github.io/crate-builder-component/)
+
 ## Add data to the crate; modify the root dataset and refresh the display
 
 ::: warning NOTE!
@@ -81,6 +83,35 @@ cm.linkEntity({
 refresh();
 ```
 
+## Add a fully resolved file or folder path to the crate
+
+As the component is embdeded into another application, it's likely the outer application will want
+to add files and folders to the crate. This can be done easily with cm from your application.
+
+```JS
+cm.addFile('/a/b/c/file.txt')
+```
+
+This will create the full path hierarchy of the file, starting from the root dataset and connected
+via hasPart (as required by the spec) with the folders as type Dataset and finally linking the file.
+
+```JS
+cm.addFolder('/a/b/c')
+```
+
+As described above but with only the folder paths.
+
+## Interact with the internal editor state
+
+The component maintains an internal editor state that has the history of paths taken through the
+crate. You can access that via `state.editorState`, e.g.:
+
+```JS
+// navigate back and forward through the history
+state.editorState.back()
+state.editorState.forward()
+```
+
 ## Change the tab being displayed
 
 This assumes you've loaded a profile with tabbed grouping.

src/docs/component/usage-and-configuration.md

@@ -49,16 +49,13 @@ let crate = mintNewCrate()
     :enable-crate-preview="true"
     :enable-browse-entities="true"
     :enable-template-save="true"
-    :enable-internal-routing="true"
     :enable-reverse-link-browser="true"
     :enable-url-markup="true"
     :enable-entity-timestamps="true"
     :purge-unlinked-entities="true"
     :readonly="false"
     :web-component="false"
     :tab-location="'left'"
-    :reset-tab-on-entity-change="true"
-    :reset-tab-on-profile-change="true"
     :show-controls="true"
     :language="language"
     @ready="ready"
@@ -138,13 +135,12 @@ for an example. In fact, you probably want to start from there.
     control
 -   `enable-template-save`: true | false: `(default: false)` : enable / disable the entity and crate
     template saving controls
--   `enable-internal-routing`: true | false: `(default: false)`: enable / disable the internal
-    router which updates the location whenever an entity is selected. If no router is found (ie
-    inside a web component or just not used), routing is turned off anyway. Most likely you want to
-    leave the component to deal with this or listen out for the `navigation` event and handle it
-    yourself if the component can't.
 -   `enable-reverse-link-browser`: true : false: `(default: true)`: enable / disable the reverse
-    link browser. If enabled, it can be shown as a right sidebar as required.
+    link browser on the right of the main metadata editor. This is useful if you want to disable the
+    component controls bar but still have access to the reverse link browser. If enabled, it can be
+    shown as a right sidebar as required. If you connect to the component via a ref (see
+    [/docs/component/advanced-usage](/docs/component/advanced-usage)), you can also control the
+    reverse link browser in code.
 -   `enable-url-markup`: true : false: `(default: true)`: When describo detects that a string is a
     URL, it will store an entity of type URL in the crate. If you would rather just have these as
     strings, set this to false (note that the URL primitive still outputs a URL entity)
@@ -159,12 +155,6 @@ for an example. In fact, you probably want to start from there.
     some components when the crate builder is used as a web component.
 -   `tab-location`: left | top | right | bottom: `(default: left)` : Specify where the tabs are
     shown when profiles define grouping.
--   `reset-tab-on-entity-change`: true | false: `(default: true)` : When true, if a layout is
-    applied and the entity changes, the UI will navigate to the about tab. If false, that doesn't
-    happen.
--   `reset-tab-on-profile-change`: true | false: `(default: true)` : When true, if a layout is
-    applied and the profile changes, the UI will navigate to the about tab. If false, that doesn't
-    happen if there is a matching tab. Otherwise it will go back to the about tab.
 -   `show-controls`: true | false: `(default: true)` : Show or hide the controls bar. Useful if you
     want to provision those controls in your own application.
 -   `language`: en | hu `(default: en)` : Sets the component's localization to the given language.