mashlib 1.7.22 → 1.8.0

package/README.md

@@ -1,43 +1,110 @@
-# Solid-compatible data mashup library and Data Browser
+# Solid-compatible data mashup library and Databrowser
 
 [![NPM Package](https://img.shields.io/npm/v/mashlib.svg)](https://www.npmjs.com/package/mashlib)
 
-The mashlib (`mashlib.js`) is a solid-compatible code library of application-level functionality for the world of Solid. One major
-use of it is as a "data browser" for a personal data store.
+The mashlib library (`mashlib.js`) is a solid-compatible code library of application-level functionality for the world of Solid. It compiles all of the following repositories into what we know as `mashlib.js`:
+- [**solid-logic**](https://github.com/solid/solid-logic) — core business logic of SolidOS
+- [**pane-registry**](https://github.com/solid/pane-registry) - an index to hold all loaded solid panes, whether statically or dynamically loaded
+- [**solid-ui**](https://github.com/solid/solid-ui) — User Interface widgets and utilities for Solid. Building blocks for solid-based apps
+- [**solid-panes**](https://github.com/solid/solid-panes) — a set of core solid-compatible panes based on solid-ui.
+
+A colorful dependency tree can be seen [here](https://github.com/solid/solidos/blob/main/documentation/solidos_dependencies.svg).
+
+## Developing mashlib
+
+As part of the SolidOS stack, mashlib can be developed locally by setting up the SolidOS code. Read more about that on the [SolidOS Readme](https://github.com/solid/solidos#-getting-started-with-the-solidos-code).
 
 ## Goals
 
-- The data browser should be a complete web-based operating system for any new computer or data store.
+The goals of mashlib overlap with the [SolidOS Goals](https://solidos.solidcommunity.net/Team/docs/SolidOSNorthStar.html).
+
+## Typical uses
 
-- When running as a native app, on laptop or desktop or mobile, it should allow the user to use their own local file system in very much the same way as a solid pod. (This currently works with Electron and rdflib). Users should be able to work **Local first**.
+One major use of mashlib is as a "databrowser" for a personal data store.
 
-- The User Interface should accommodate a wide range of devices, screen sizes, bandwidth.  The project was originally targeted at laptop, and reactive design is important in new work.
+Mashlib is used in SolidOS and contributes to:
 
-- The data browser, unlike a typical set of native applications, is very interconnected.  You can do anything with anything - so data from different applications interlinks in a more powerful way so as to solve real life problems powerfully and naturally. You can start a chat about anything, with anyone.  You can adopt anything as the target of a task you want to track later. You can like, flag, keyword, bookmark anything.  So one application will use others in a recursive way to get its job done.  
+- SolidOS Databrowser Frontend - a frontend for Solid Servers like <solidcommunity.net>
+- SolidOS Data-Kitchen - a stand-alone desktop app: <https://github.com/solid/data-kitchen>
 
-- You should be able to set the data browser up for any **existing** folders you have full of things like photos and music, and it should let you listen to them, look at them, and share them very flexibly with anyone in the world.
+mashlib is also used stand-alone as the SolidOS Databrowser Webapp and can be tried out at <https://solid.github.io/mashlib/dist/browse.html>.
 
-- When used with a Solid pod, because that is on the web, the data browser provides the **public view** -- the interactive interface -- that the user has with the rest of the world.  Like when everyone had their own home page on the web, they have that power again to express themselves and their affiliation and their products, and to court interaction, such as collaborative work with others, or commerce.  The way this public home page appears to others is very customizable, so the user, individual or business can be proud of it.
+mashlib is also used as a library by adding `mashlib.js` (or minified version) directly to your applications. For example:
 
-- The data browser should be modular, **dynamically** loading new code modules in real time as a function of a user's preferences for handling different types of data with different new data browser applets, be it finance, fitness, or fishing.
+`<script src="https://solidcommunity.net/mashlib.js"></script>`.
 
-- A module providing new functionality in a new domain should be able to appear as a module in the data browser or as a stand-alone app, or both.
+## Previous versions of this documentation
 
-- The modularity of the system should allow you set yourself up with any set of apps, or indeed the user should be able to configure the data browser to replace itself with the user's own choice of alternative data browser.  All data browsers should allow the user to change this selection.
+Check out [SolidOS Pod](https://solidos.solidcommunity.net/Team/docs/solidos.html) for an earlier version of this documentation.
 
-- The data browser should allow people to create, bit by bit, a web of social linked data of their work and their play, and their lives.
+# Documentation
 
+## Different implementations
 
-## Typical uses
+### SolidOS Databrowser Webapp
+
+The `static/browse.html` page is compiled one to one into the `dist` (output) folder of mashlib and makes mashlib available stand-alone as the SolidOS Databrowser Webapp.
+
+You can see and try out a SolidOS Databrowser Webapp deployment at <https://solid.github.io/mashlib/dist/browse.html>.
+
+`browse.html`serves as a perfect example for Solid WebID authentication and for making use of mashlib functions and variables.
+
+### SolidOS Databrowser Frontend
+
+The `src/databrowser.html`page is compiled into the SolidOS Databrowser Frontend which is displayed for each WebID on [solidcommunity.net](https://solidcommunity.net/). This is the case because the [solidcommunity.net](https://solidcommunity.net/) Solid Server is configured with SolidOS as its front-end.
+
+More information about the SolidOS Front-end and how to use it visit the [User Guide](https://github.com/solid/userguide).
+
+### SolidOS Data-Kitchen
+
+SolidOS Data-Kitchen uses `mashlib.js`as a direct import in its source code. Visit the code at [SolidOS Data-Kitchen GitHub](https://github.com/solid/data-kitchen).
+
+## Mashlib global variables and functions
+
+If one wants to use mashlib as a direct import (as a package dependency or script import), one needs to know which global variables and functions are available.
+
+The availability of these global variables depends on how the sub-modules are imported and exported and on where the variables are instantiated. For a basic theoretical read, please see [this resource](https://www.javatpoint.com/javascript-global-variable).
+
+What does `global` mean in mashlib? We mean the `global object` which depends on different environments. In mashlib, for now, we use the `window` context which means these variables will not work if directly used in non-window contexts such as `Node.js` environments. (This does not mean you cannot use mashlib in `Node.js` environments; just import it through `npm`). At some point, we will switch this to the [`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis).
 
-The mashlib can be used as the core of a native application.  It has been tried on Mac OS using **electron**. 
-The mashlib has been used before, originally in various apps, in specific data interactions in different
-domains. It has been used in a **browser extension** (in Firefox and later Chrome) to add data-handling
-capacity as native to the browser itself. Several (personal) data stores will serve this HTML view as a
-sort of poor person's data browser extension, which loads the library and then tries to work as though
-the browser had been extended to understand data.
+These are the most important window context/global variables and the sub-repos from which they are exported:
 
-## The data browser hack: upgrading your browser
+- [**solid-logic**](https://github.com/solid/solid-logic/blob/f606b31382a416ee6188930c3ca05cb4ae73cbda/src/index.ts#L29) exports among others: `solidLogicSingleton`, `authn`, `authSession`, `store`, `chat`, `profile`
+- [**pane-registry**](https://github.com/solid/pane-registry) is exported entirely through the pane-registry variable
+- [**solid-ui**](https://github.com/solid/solid-ui/blob/c5a8888d6cb61363bc0445be007e3c96de593338/src/index.ts#L79) exports among others: authn, store, rdf, dom under the `UI` variable
+- [**solid-panes**](https://github.com/solid/solid-panes/blob/033f48f8987364cb131455b13e8b0637da95a5ab/src/index.ts#L53) exports getOutliner and the entire solid-ui through the `UI` variable, and solid-panes itself can be used through the `panes` variable
+
+For backward compatibility reasons, there are now different ways to make use of the same variables from mashlib. For example:
+
+- to make use of the UI (solid-ui) one can use `UI` or `panes.UI`
+- authentication session, part of solid-logic, can be called as `authSession` or `UI.authn.authSession` or `panes.UI.authn.authSession`
+- the store (from solid-logic) can be used as `store` or `UI.store` or `panes.UI.store`
+- rdflib is entirely acessible as `UI.rdf` or `panes.UI.rdf`
+- the currentUser function is called as `authn.currentUser()` or `UI.auth.currentUser()` or `panes.UI.authn.currentUser()`
+- to make use of the login pop-up, one needs to call the `UI.login.loginStatusBox` function
+
+You can see example usage in the [SolidOS Databrowser Webapp code](https://github.com/solid/mashlib/blob/main/static/browse.html#L11).
+
+## Code changes due to moving authn from solid-ui to solid-logic
+
+Some packages have been moved and with them some functions too. Here we report on these changes:
+
+### Solid-ui & Solid-logic related:
+
+* There is no more `authn` as you might have known it in solid-ui pre mashlib version 1.7.18 (solid-ui 2.4.16).
+* Some functions in solid-ui which initially were found under `solid-ui/authn` are now under `solid-ui/login`.
+* Two functions were renamed:
+    * logInLoadPreferences -> ensureLoadedPreferences 
+    * logInLoadProfile -> ensureLoadedProfile
+    * logIn -> ensureLoggedIn
+
+Functions that moved: 
+
+* `currentUser`, `checkUser`, `saveUser`, `offlineTestID` are now part of `solid-logic/authn/SolidAuthnLogic.ts`-> this is because `authn` itself moved to solid-logic. 
+* `setACLUserPublic`, `fetchACLRel` are not part of `solid-logic/src/acl/aclLogic.ts/` and are exported in [index.ts](https://github.com/solid/solid-logic/blob/f606b31382a416ee6188930c3ca05cb4ae73cbda/src/index.ts#L12).
+* `loadIndex`, `loadTypeIndexes`, `ensureTypeIndexes`, `registerInTypeIndex` and are exported in [index.ts](https://github.com/solid/solid-logic/blob/f606b31382a416ee6188930c3ca05cb4ae73cbda/src/index.ts#L16).
+
+## The databrowser hack: upgrading your browser
 
 This refers to a specific way in which the mashlib is deployed for users who at first only have a conventional web browser - a hypertext browser not a data browser.  It is a hack -- in the original computing sense of a crafty, though not beautiful, little thing which gets the job done.
 
@@ -51,27 +118,7 @@ How does the data browser work?
 1. The server supplies the actual data of the to-do list or whatever it was.
 1. The `mashlib.js` code provides an editable visualization on the data.
 
-The mashlib human interface is *read-write*: where the user is allowed to edit: it lets them edit the data and create new things.  It is *live*, in that often the data browser signed up (using a websocket) for any changes which other users make, so users' screens are synchronized.
-
-A major limitation of their data browser hack is that current web browsers are made to distrust any code loaded from one domain that uses data from another domain.  This makes it hard, strangely complicated, and sometimes impossible to do some things.
-
-## History: Why "Mashlib"?
-
-What is a data mashup?  [A mashup](https://en.wikipedia.org/wiki/Mashup_%28web_application_hybrid%29)
-is a web page which is built out of data coming from more than one source.  
-
- Mashups are important because they are fun and because fundamentally, the value
- of data is much greater when data of one source is combined with linked data from another, because that is where you can get extra insights.
-  [My TED talk on open data examples](https://www.ted.com/talks/tim_berners_lee_the_year_open_data_went_worldwide#t-81407)
-  has some examples.
-Data mashups were all the rage back 2012-2017, although the browser's [Same Origin Policy](https://en.wikipedia.org/wiki/Same-origin_policy) in many cases makes them hard to do or impossible in a web app, as the data access is blocked by the browser code.
+The mashlib part of SolidOS Databrowser Frontend is *read-write;* that is, the user is allowed to edit data and create new things. It is *live,* in that often the databrowser subscribed (using a websocket) for any changes which other users make, so users' screens are synchronized.
 
-The mashlib started life motivated by the drive to build quick visualizations of data from different sources. Typically, documents or query results are all loaded into the quadstore, so the relationships between different things can be visualized.  The "tabulator" project developed the original mashlib.
+A major limitation of this data browser hack is that current web browsers are made to distrust any code loaded from one domain that uses data from another domain. This makes it hard, strangely complicated, and sometimes impossible to do some things.
 
-Progressively, the mashlib evolved to allow types of data for personal information management (contacts, etc) and social (chat, shared documents, issue tracking, music, photos) and also as a file browser for a Solid-compatible personal data store (files, folders, and sharing). Now, the mashlib is a general-purpose tool for doing all kinds of useful things.
-
-It is an extensible platform, and is never finished.  Do help!  
-
-## Local development
-
-As part of the SolidOS stack, mashlib can be developed locally by setting up the SolidOS code. Read more about that on the [SolidOS Readme](https://github.com/solid/solidos#-getting-started-with-the-solidos-code).

package/dist/databrowser.html

@@ -1,3 +1,3 @@
 <!doctype html><html><head><meta charset="utf-8"/><title>SolidOS Web App</title><script>document.addEventListener('DOMContentLoaded', function() {
         panes.runDataBrowser()
-      })</script><link href="/mash.css" rel="stylesheet"></head><body class="db-layout"><header class="db-layout__header header" id="PageHeader"></header><div class="TabulatorOutline db-layout__content" id="DummyUUID" role="main"><table id="outline"></table><div id="GlobalDashboard"></div></div><footer class="db-layout__footer" id="PageFooter"></footer><script src="/mashlib.min.js"></script></body></html>
+      })</script><link href="/mash.css" rel="stylesheet"></head><body id="PageBody"><header id="PageHeader"></header><div class="TabulatorOutline" id="DummyUUID" role="main"><table id="outline"></table><div id="GlobalDashboard"></div></div><footer id="PageFooter"></footer><script src="/mashlib.min.js"></script></body></html>