From 125cbc7948cbe499f09722cb3ae90b5cb662fedf Mon Sep 17 00:00:00 2001 From: Winzlieb Date: Thu, 8 Aug 2024 12:23:02 +0200 Subject: [PATCH] restructuring the storybook and add documentation --- README.md | 7 +-- .../form/EditExhibitionJSONForm.stories.tsx | 2 +- .../components/form/Form.stories.tsx | 2 +- .../DeepGraphToJSONShowcase.stories.tsx | 2 +- .../form/lobid/LobidAllPropsTable.stories.tsx | 2 +- .../form/lobid/LobidAutocomplete.stories.tsx | 2 +- .../form/lobid/LobidSearchTable.stories.tsx | 2 +- .../form/show/EntityDetailCard.stories.tsx | 2 +- .../form/wikidata/Wikidata.stories.tsx | 2 +- .../WikidataAutocompleteInput.stories.tsx | 2 +- .../layout/main-layout/MainLayout.stories.tsx | 2 +- .../AutocompleteURIFieldRenderer.stories.tsx | 2 +- apps/exhibition-live/stories/Development.mdx | 37 ------------ .../stories/{ => architecture}/DataStore.mdx | 47 ++++++++++++++- .../{ => development}/ProblemSolving.mdx | 4 ++ .../stories/maintenance/Cli.mdx | 60 +++++++++++++++++++ .../stories/maintenance/DataImport.mdx | 2 +- .../stories/{ => maintenance}/DataMapping.mdx | 2 +- .../search/DiscoverSearchTable.stories.tsx | 2 +- .../src/AutoIdentifierRenderer.stories.tsx | 2 +- .../special-date/AdbSpecialDate.stories.tsx | 2 +- .../MaterialCustomOnyOfRenderer.stories.tsx | 2 +- .../src/SemanticJSONFormNoOps.stories.tsx | 2 +- .../src/MarkdownTextFieldRenderer.stories.tsx | 2 +- 24 files changed, 132 insertions(+), 61 deletions(-) rename apps/exhibition-live/stories/{ => architecture}/DataStore.mdx (72%) rename apps/exhibition-live/stories/{ => development}/ProblemSolving.mdx (91%) create mode 100644 apps/exhibition-live/stories/maintenance/Cli.mdx rename apps/exhibition-live/stories/{ => maintenance}/DataMapping.mdx (99%) diff --git a/README.md b/README.md index 1109466d..5a3dfa04 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,10 @@ A live demo of the exhibition catalog is available here: [https://slub.github.io You might want to set your own storage backend(s) within the settings modal. -## Storybook stories +## Development Documentation -The pure frontend specific component based framework, that sets the base of the exhibition catalog is documented within the Storybook. - -You can get a live preview of the current `develop` branch here: [https://slub.github.io/exhibition-live/storybook/](https://slub.github.io/exhibition-live/storybook/) +Please have a look at the **[Storybook of the EDB Framework](https://slub.github.io/exhibition-live/storybook/)** for an indepth documentation of the frontend components, th cli +and the overall architecture of the exhibition catalog and the EDB framework. # Development diff --git a/apps/exhibition-live/components/form/EditExhibitionJSONForm.stories.tsx b/apps/exhibition-live/components/form/EditExhibitionJSONForm.stories.tsx index 8e3ef257..313519ad 100644 --- a/apps/exhibition-live/components/form/EditExhibitionJSONForm.stories.tsx +++ b/apps/exhibition-live/components/form/EditExhibitionJSONForm.stories.tsx @@ -59,6 +59,6 @@ export const SemanticJsonFormExhibition = () => { ); }; export default { - title: "form/exhibition/EditExhibitionJSONForm", + title: "ui/form/EditExhibitionJSONForm", component: NewSemanticJsonForm, }; diff --git a/apps/exhibition-live/components/form/Form.stories.tsx b/apps/exhibition-live/components/form/Form.stories.tsx index 6c46fc5e..c2205eee 100644 --- a/apps/exhibition-live/components/form/Form.stories.tsx +++ b/apps/exhibition-live/components/form/Form.stories.tsx @@ -2,7 +2,7 @@ import TypedForm from "../content/main/TypedForm"; import { sladb } from "../config/formConfigs"; export default { - title: "forms/Form", + title: "ui/form/Examples", component: TypedForm, }; diff --git a/apps/exhibition-live/components/form/deep-graph/DeepGraphToJSONShowcase.stories.tsx b/apps/exhibition-live/components/form/deep-graph/DeepGraphToJSONShowcase.stories.tsx index 2c7f3ad5..7dabbf06 100644 --- a/apps/exhibition-live/components/form/deep-graph/DeepGraphToJSONShowcase.stories.tsx +++ b/apps/exhibition-live/components/form/deep-graph/DeepGraphToJSONShowcase.stories.tsx @@ -2,7 +2,7 @@ import DeepGraphToJSONShowcase from "./DeepGraphToJSONShowcase"; import { Meta, StoryObj } from "@storybook/react"; export default { - title: "form/exhibition/DeepGraphToJSONShowcase", + title: "architecture/graph-data/DeepGraphToJSONShowcase", component: DeepGraphToJSONShowcase, } as Meta; diff --git a/apps/exhibition-live/components/form/lobid/LobidAllPropsTable.stories.tsx b/apps/exhibition-live/components/form/lobid/LobidAllPropsTable.stories.tsx index f866819c..8ff71bfb 100644 --- a/apps/exhibition-live/components/form/lobid/LobidAllPropsTable.stories.tsx +++ b/apps/exhibition-live/components/form/lobid/LobidAllPropsTable.stories.tsx @@ -2,7 +2,7 @@ import React from "react"; import { LobidAllPropTable } from "@slub/edb-advanced-components"; export default { - title: "presentation/lobid/LobidAllPropsTable", + title: "ui/view/LobidAllPropsTable", component: LobidAllPropTable, }; diff --git a/apps/exhibition-live/components/form/lobid/LobidAutocomplete.stories.tsx b/apps/exhibition-live/components/form/lobid/LobidAutocomplete.stories.tsx index f2ef0c83..7df0fe10 100644 --- a/apps/exhibition-live/components/form/lobid/LobidAutocomplete.stories.tsx +++ b/apps/exhibition-live/components/form/lobid/LobidAutocomplete.stories.tsx @@ -3,7 +3,7 @@ import React from "react"; import LobidAutocompleteSearch from "./LobidAutocompleteSearch"; export default { - title: "form/lobid/LobidAutocomplete", + title: "ui/form/LobidAutocomplete", component: LobidAutocompleteSearch, }; diff --git a/apps/exhibition-live/components/form/lobid/LobidSearchTable.stories.tsx b/apps/exhibition-live/components/form/lobid/LobidSearchTable.stories.tsx index 1d6faeb6..441f73bd 100644 --- a/apps/exhibition-live/components/form/lobid/LobidSearchTable.stories.tsx +++ b/apps/exhibition-live/components/form/lobid/LobidSearchTable.stories.tsx @@ -4,7 +4,7 @@ import LobidSearchTable from "./LobidSearchTable"; import { sladb } from "../../config/formConfigs"; export default { - title: "form/lobid/LobidSearchTable", + title: "ui/form/LobidSearchTable", component: LobidSearchTable, }; diff --git a/apps/exhibition-live/components/form/show/EntityDetailCard.stories.tsx b/apps/exhibition-live/components/form/show/EntityDetailCard.stories.tsx index 856ee012..b7617484 100644 --- a/apps/exhibition-live/components/form/show/EntityDetailCard.stories.tsx +++ b/apps/exhibition-live/components/form/show/EntityDetailCard.stories.tsx @@ -2,7 +2,7 @@ import { Meta, StoryObj } from "@storybook/react"; import { EntityDetailCard } from "@slub/edb-advanced-components"; export default { - title: "presentation/kb/EntityDetailCard", + title: "ui/view/EntityDetailCard", component: EntityDetailCard, } as Meta; diff --git a/apps/exhibition-live/components/form/wikidata/Wikidata.stories.tsx b/apps/exhibition-live/components/form/wikidata/Wikidata.stories.tsx index 6eec9a87..9242ee48 100644 --- a/apps/exhibition-live/components/form/wikidata/Wikidata.stories.tsx +++ b/apps/exhibition-live/components/form/wikidata/Wikidata.stories.tsx @@ -5,7 +5,7 @@ import WikidataThingCard from "./WikidataThingCard"; import WikidataHumanCard from "./WikidataHumanCard"; export default { - title: "form/wikidata/WikidataThingCard", + title: "ui/view/WikidataCard", component: WikidataThingCard, }; diff --git a/apps/exhibition-live/components/form/wikidata/WikidataAutocompleteInput.stories.tsx b/apps/exhibition-live/components/form/wikidata/WikidataAutocompleteInput.stories.tsx index af82cd2f..aa8ea862 100644 --- a/apps/exhibition-live/components/form/wikidata/WikidataAutocompleteInput.stories.tsx +++ b/apps/exhibition-live/components/form/wikidata/WikidataAutocompleteInput.stories.tsx @@ -3,7 +3,7 @@ import React from "react"; import WikidataAutocompleteInput from "./WikidataAutocompleteInput"; export default { - title: "form/wikidata/WikidataAutoCompleteInput", + title: "ui/form/WikidataAutoCompleteInput", component: WikidataAutocompleteInput, }; diff --git a/apps/exhibition-live/components/layout/main-layout/MainLayout.stories.tsx b/apps/exhibition-live/components/layout/main-layout/MainLayout.stories.tsx index d0890a2d..544fe776 100644 --- a/apps/exhibition-live/components/layout/main-layout/MainLayout.stories.tsx +++ b/apps/exhibition-live/components/layout/main-layout/MainLayout.stories.tsx @@ -7,7 +7,7 @@ import { sladb, slent } from "../../config/formConfigs"; import { QueryClientProvider, QueryClient } from "@slub/edb-state-hooks"; export default { - title: "layout/MainLayout", + title: "ui/layout/MainLayout", component: MainLayout, } as Meta; diff --git a/apps/exhibition-live/components/renderer/AutocompleteURIFieldRenderer.stories.tsx b/apps/exhibition-live/components/renderer/AutocompleteURIFieldRenderer.stories.tsx index a7d4d2a9..51758a03 100644 --- a/apps/exhibition-live/components/renderer/AutocompleteURIFieldRenderer.stories.tsx +++ b/apps/exhibition-live/components/renderer/AutocompleteURIFieldRenderer.stories.tsx @@ -16,7 +16,7 @@ import { useCallback, useState } from "react"; import AutocompleteURIFieldRenderer from "./AutocompleteURIFieldRenderer"; export default { - title: "form/exhibition/AutocompleteURIFieldRenderer", + title: "ui/form/renderer/AutocompleteURIFieldRenderer", component: AutocompleteURIFieldRenderer, }; diff --git a/apps/exhibition-live/stories/Development.mdx b/apps/exhibition-live/stories/Development.mdx index 54df58c7..16283c1b 100644 --- a/apps/exhibition-live/stories/Development.mdx +++ b/apps/exhibition-live/stories/Development.mdx @@ -31,43 +31,6 @@ within the `@slub` namespace. It will build all packages in parallel, and contin The `apps` directory contains concrete applications that use the EDB Framework. These applications are built using dependencies, from the workspace within the `packages` and `manifestations` directory. -### EDB Cli - -The EDB Cli is a command-line tool for accessing and mapping data according to the current EDB data model defined by the JSON Schema. - -To run the EDB Cli, run the following command: - -```bash -bun run cli -``` -It will show you the available subcommands and options. - -``` -edb-cli - -where can be one of: - -- list -- get -- flatImport - Import of flat table structured documents -- import - Recursively import data from another data store - -For more help, try running `edb-cli --help` -``` - -#### Retrieving Data - -Use the list or get command to retrieve data from the EDB Cli. The list command will list all documents, while the get command will retrieve a specific data object. - -```bash -bun run cli list Person -n 10 -``` -will list 10 documents of the type `Person`. - -```bash -bun run cli get Person http://ontologies.slub-dresden.de/exhibition/entity#XYZ -``` -will retrieve the document with the id `http://ontologies.slub-dresden.de/exhibition/entity#XYZ` of the type `Person`. ## Versioning diff --git a/apps/exhibition-live/stories/DataStore.mdx b/apps/exhibition-live/stories/architecture/DataStore.mdx similarity index 72% rename from apps/exhibition-live/stories/DataStore.mdx rename to apps/exhibition-live/stories/architecture/DataStore.mdx index b961b588..68f98dd7 100644 --- a/apps/exhibition-live/stories/DataStore.mdx +++ b/apps/exhibition-live/stories/architecture/DataStore.mdx @@ -1,6 +1,7 @@ import { Meta } from "@storybook/blocks"; +import {SBMermaid} from "../../.storybook/blocks/SBMermaid"; - + # Data Stores @@ -15,6 +16,50 @@ to create the necessary indexes during the bootstrap phase. The reference implementation is using the SPARQL query language to provide a RDF based data store, that can be used from the client and the server. +Dependending on the DataStore the overall architecture will look different. A client side approach, that does not require a classical +Backend will look like the following + + ds[/SPARQL-DataStore\\] + end + ds --> id1[(SPARQL-Database \n e.g. Oxigraph, Allegro, QLever )]`}> + +For testing purpose it can even be a local in memory SPARQL Database (driven by a webworker) + + ds[/SPARQL-DataStore \n with local worker config\\] --> id1[(in memory Oxigraph)] + end + id1 -- export/download --> tr[Triples export.ttl or export.json]`}> + + +When using the Restful-DataStore within the client and the SPARQL-DataStore within the Backend the chart will +look like the following: + + ds[/RESTfull-DataStore\\] + end + ds -- REST request --> rh[REST Request Handler] + subgraph Server + rh --> ds2[/SPARQL-DataStore\\] + end + ds2 --> id1[(SPARQL-Database)]`}> + +Another example would be Prisma in combination with Postgres: + + + ds[/RESTfull-DataStore\\] + end + ds -- REST request --> rh[REST Request Handler] + subgraph Server + rh --> ds2[/Prisma-DataStore\\] --> PrismaORM + end + PrismaORM --> id1[(Postgres)]`}> + ## SPARQL Data Store diff --git a/apps/exhibition-live/stories/ProblemSolving.mdx b/apps/exhibition-live/stories/development/ProblemSolving.mdx similarity index 91% rename from apps/exhibition-live/stories/ProblemSolving.mdx rename to apps/exhibition-live/stories/development/ProblemSolving.mdx index 9037a2ac..760ee785 100644 --- a/apps/exhibition-live/stories/ProblemSolving.mdx +++ b/apps/exhibition-live/stories/development/ProblemSolving.mdx @@ -1,3 +1,7 @@ +import { Meta } from "@storybook/blocks"; + + + # Problem Solving This package is dedicated to problems that can occur during development and how to solve them. diff --git a/apps/exhibition-live/stories/maintenance/Cli.mdx b/apps/exhibition-live/stories/maintenance/Cli.mdx new file mode 100644 index 00000000..76fa5812 --- /dev/null +++ b/apps/exhibition-live/stories/maintenance/Cli.mdx @@ -0,0 +1,60 @@ +import { Meta } from "@storybook/blocks"; +import {SBMermaid} from "../../.storybook/blocks/SBMermaid"; + + + + +# EDB Cli + +The EDB Cli is a command-line tool for accessing and mapping data according to the current EDB data model defined by the JSON Schema. + +The Cli will use the global configuration provided by the environment (for example `.env` file) to connect to the configured DataStore +and what model to use. + +The CLI also supports a list of Import-DataStores, which can be used to import data from other data sources. +The data flow looks as follows (in the example a Prisma DataStore is being used) : + + + + ds2[/Main-DataStore\\] --> PrismaORM + ds3[/Import-DataStore 1\\] -- import --> ds2 + ds4[/Import-DataStore 2\\] -- import --> ds2 + end + CLI -- output --> jsonld[JSON-LD Documents] + PrismaORM --> id1[(Postgres)]`}> + +To run the EDB Cli, run the following command: + +```bash +bun run cli +``` +It will show you the available subcommands and options. + +``` +edb-cli + +where can be one of: + +- list +- get +- flatImport - Import of flat table structured documents +- import - Recursively import data from another data store + +For more help, try running `edb-cli --help` +``` + +#### Retrieving Data + +Use the list or get command to retrieve data from the EDB Cli. The list command will list all documents, while the get command will retrieve a specific data object. + +```bash +bun run cli list Person -n 10 +``` +will list 10 documents of the type `Person`. + +```bash +bun run cli get Person http://ontologies.slub-dresden.de/exhibition/entity#XYZ +``` +will retrieve the document with the id `http://ontologies.slub-dresden.de/exhibition/entity#XYZ` of the type `Person`. diff --git a/apps/exhibition-live/stories/maintenance/DataImport.mdx b/apps/exhibition-live/stories/maintenance/DataImport.mdx index 030d8e0d..2a064906 100644 --- a/apps/exhibition-live/stories/maintenance/DataImport.mdx +++ b/apps/exhibition-live/stories/maintenance/DataImport.mdx @@ -3,7 +3,7 @@ import { Meta } from "@storybook/blocks"; -#### Importing Data +# Importing Data from other Data Stores Two kinds of import commands are available in the EDB Cli. The `flatImport` command will import flat table structured documents for example CSV files and the `import` command will recursively import data from another data store. diff --git a/apps/exhibition-live/stories/DataMapping.mdx b/apps/exhibition-live/stories/maintenance/DataMapping.mdx similarity index 99% rename from apps/exhibition-live/stories/DataMapping.mdx rename to apps/exhibition-live/stories/maintenance/DataMapping.mdx index 002700e0..3202b341 100644 --- a/apps/exhibition-live/stories/DataMapping.mdx +++ b/apps/exhibition-live/stories/maintenance/DataMapping.mdx @@ -1,6 +1,6 @@ import { Meta } from "@storybook/blocks"; - + The typical work with a domain specific database is to map data from a secondary data source into the primary datasource, thus making the data available for the specific use case and normalize the diff --git a/packages/advanced-components/src/search/DiscoverSearchTable.stories.tsx b/packages/advanced-components/src/search/DiscoverSearchTable.stories.tsx index cb69ffe3..575c8b3d 100644 --- a/packages/advanced-components/src/search/DiscoverSearchTable.stories.tsx +++ b/packages/advanced-components/src/search/DiscoverSearchTable.stories.tsx @@ -3,7 +3,7 @@ import React from "react"; import { DiscoverSearchTable } from "./DiscoverSearchTable"; export default { - title: "form/discover/DiscoverSearchTable", + title: "ui/form/DiscoverSearchTable", component: DiscoverSearchTable, }; diff --git a/packages/form-renderer/basic-renderer/src/AutoIdentifierRenderer.stories.tsx b/packages/form-renderer/basic-renderer/src/AutoIdentifierRenderer.stories.tsx index f695535b..3774eb5d 100644 --- a/packages/form-renderer/basic-renderer/src/AutoIdentifierRenderer.stories.tsx +++ b/packages/form-renderer/basic-renderer/src/AutoIdentifierRenderer.stories.tsx @@ -9,7 +9,7 @@ import { useCallback, useState } from "react"; import { AutoIdentifierRenderer } from "./AutoIdentifierRenderer"; export default { - title: "form/exhibition/AutoIdentifierRenderer", + title: "ui/form/renderer/AutoIdentifierRenderer", component: AutoIdentifierRenderer, }; diff --git a/packages/form-renderer/basic-renderer/src/special-date/AdbSpecialDate.stories.tsx b/packages/form-renderer/basic-renderer/src/special-date/AdbSpecialDate.stories.tsx index c4fa0b27..8d8e92cb 100644 --- a/packages/form-renderer/basic-renderer/src/special-date/AdbSpecialDate.stories.tsx +++ b/packages/form-renderer/basic-renderer/src/special-date/AdbSpecialDate.stories.tsx @@ -3,7 +3,7 @@ import { Meta, StoryObj } from "@storybook/react"; import { AdbSpecialDateFormGroup } from "./AdbSpecialDateFormGroup"; export default { - title: "form/exhibition/AdbSpecialDateFormGroup", + title: "ui/form/renderer/AdbSpecialDateFormGroup", component: AdbSpecialDateFormGroup, argTypes: { data: { control: false }, diff --git a/packages/form-renderer/layout-renderer/src/MaterialCustomOnyOfRenderer.stories.tsx b/packages/form-renderer/layout-renderer/src/MaterialCustomOnyOfRenderer.stories.tsx index e887b04a..887110d8 100644 --- a/packages/form-renderer/layout-renderer/src/MaterialCustomOnyOfRenderer.stories.tsx +++ b/packages/form-renderer/layout-renderer/src/MaterialCustomOnyOfRenderer.stories.tsx @@ -9,7 +9,7 @@ import { MaterialCustomAnyOfRenderer } from "./MaterialCustomAnyOfRenderer"; import { materialCustomAnyOfControlTester } from "./materialCustomAnyOfControlTester"; export default { - title: "form/exhibition/MaterialCustomAnyOfRenderer", + title: "ui/form/renderer/MaterialCustomAnyOfRenderer", component: MaterialCustomAnyOfRenderer, }; diff --git a/packages/form-renderer/linked-data-renderer/src/SemanticJSONFormNoOps.stories.tsx b/packages/form-renderer/linked-data-renderer/src/SemanticJSONFormNoOps.stories.tsx index 5de2e1d3..9052653d 100644 --- a/packages/form-renderer/linked-data-renderer/src/SemanticJSONFormNoOps.stories.tsx +++ b/packages/form-renderer/linked-data-renderer/src/SemanticJSONFormNoOps.stories.tsx @@ -9,7 +9,7 @@ const sladb = namespace("http://ontologies.slub-dresden.de/exhibition#"); const slent = namespace("http://ontologies.slub-dresden.de/exhibition/entity#"); export default { - title: "form/exhibition/SemanticJsonFormNoOps", + title: "ui/form/SemanticJsonForm", component: SemanticJsonFormNoOps, } as Meta; diff --git a/packages/form-renderer/markdown-renderer/src/MarkdownTextFieldRenderer.stories.tsx b/packages/form-renderer/markdown-renderer/src/MarkdownTextFieldRenderer.stories.tsx index ebeaba75..79038052 100644 --- a/packages/form-renderer/markdown-renderer/src/MarkdownTextFieldRenderer.stories.tsx +++ b/packages/form-renderer/markdown-renderer/src/MarkdownTextFieldRenderer.stories.tsx @@ -10,7 +10,7 @@ import { materialCustomAnyOfControlTester } from "@slub/edb-layout-renderer"; import { MarkdownTextFieldRenderer } from "./MarkdownTextFieldRenderer"; export default { - title: "form/exhibition/MarkdownTextFieldRenderer", + title: "ui/form/renderer/MarkdownTextFieldRenderer", component: MarkdownTextFieldRenderer, };