Skip to content
This repository has been archived by the owner on Nov 27, 2022. It is now read-only.

Latest commit

 

History

History
203 lines (170 loc) · 7.31 KB

README.md

File metadata and controls

203 lines (170 loc) · 7.31 KB
Raw

React for Solid

Basic React components for building your own Solid components and apps.

npm version Build Status Coverage Status Dependency Status

🚧 Work in progress: you currently get components to read data. Writing is still underway.

Purpose

✨ Solid is an ecosystem for people, data, and apps in which people can store their data where they want, independently of the apps they use.

⚛️ This library aims to:

  1. provide React developers with components to develop fun Solid apps 👨🏿‍💻
  2. enable React developers to build their own components for Solid 👷🏾‍♀️

Solid uses 🔗 Linked Data, so people's data from all over the Web can be connected together instead of needing to be stored in one giant space. This library makes working with Linked Data easier, too.

Example apps

These apps have already been built with React for Solid:

Installation and usage

First add the package:

yarn add @solid/react # or
npm install @solid/react

Then you can import components like this:

import { LoginButton, Value } from '@solid/react';

Components

The demo app will inspire you on how to use the components listed below.

👮🏻‍♀️ Authentication

Showing different content to logged in users

<LoggedOut>
  <p>You are not logged in, and this is a members-only area!</p>
</LoggedOut>
<LoggedIn>
  <p>You are logged in and can see the special content.</p>
</LoggedIn>

Logging in and out

You will need a copy of popup.html in your application folder.

<LoginButton popup="popup.html"/>
<LogoutButton>Log me out</LogoutButton>
// Shows LoginButton or LogoutButton depending on the user's status
<AuthButton popup="popup.html" login="Login here!" logout="Log me out"/>

🖥️ Showing Solid data

🈯 The LDflex language

Solid React data components use the LDFlex language to build paths to the data you want.

For example:

  • "user.firstName" will resolve to the logged in user's first name
  • "user.friends.firstName" will resolve to the first name of the user's friends
  • "[https://ruben.verborgh.org/profile/#me].homepage" will resolve to Ruben's homepage
  • "[https://ruben.verborgh.org/profile/#me].friends.firstName" will resolve to Ruben's friends' names

Learn how to write your own LDflex expressions.

Data components

<LoggedIn>
  <p>Welcome back, <Value src="user.firstName"/></p>
  <Image src="user.image" defaultSrc="profile.svg" className="pic"/>
  <ul>
    <li><Link href="user.inbox">Your inbox</Link></li>
    <li><Link href="user.homepage">Your homepage</Link></li>
  </ul>
</LoggedIn>

<h2>Random friend of <Name src="[https://ruben.verborgh.org/profile/#me]"/></h2>
<Value src="[https://ruben.verborgh.org/profile/#me].friends.firstName"/>

<h2>All friends</h2>
<List src="[https://ruben.verborgh.org/profile/#me].friends.firstName"/>

<h2>Random blog post</h2>
<Link href="[https://ruben.verborgh.org/profile/#me].blog[schema:blogPost]"/>

<h2>All blog posts</h2>
<List src="[https://ruben.verborgh.org/profile/#me].blog[schema:blogPost].label"/>

💪🏾 Building your own components

The Solid React library makes it easy to build your own components to interact with the current user and to fetch Linked Data from the Web. To this end, the library ships with Higher-Order Components that do the heavy lifting for your components.

The easiest way is to look at the implementation of built-in components like AuthButton, Name, and List. They are all relatively straightforward, since the complexity is abstracted by the mechanisms listed below.

import { withWebId, evaluateExpressions, evaluateList } from '@solid/react';

Components that access the user's WebID

In Solid, people are identified by a WebID, which is a URL that points to them and leads to their data.

By wrapping your component definition with withWebId, the user's WebID will automatically be set on the webId property of your component whenever the login status changes. If it is undefined, the login status is still loading; null signals the user is not logged in.

const MyComponent = withWebId(props =>
  <p>Hey user, your WebID is {props.webID}.</p>);
<MyComponent/>

Components that use LDflex expressions

To use data from LDflex expressions, wrap your component definition with evaluateExpressions. The first argument is an array of properties in which you expect expressions. Your component will then get back the result in the property of the same name.

const MyComponent = evaluateExpressions(['name'], props =>
  <p>The name is {`${props.name}`}.</p>);
<MyComponent name="user.friends.name"/>

Note how we force props.name into a string through ${props.name} (or, alternatively, props.name.toString() or '' + props.name). This is needed because props.name is a special object that looks like a string but isn't quite a string.

If a property contains a list of things rather than a single value, pass its name to the second parameter:

const MyComponent = evaluateExpressions(['name'], ['friends'], props =>
  <p>Your name is {`${props.name}`} and you have {props.friends.length} friends.</p>);
<MyComponent name="user.name" friends="user.friends"/>

Specifically for building lists of things, there is the evaluateList helper. The built-in List component is an example.

const Greetings = evaluateList('people', ({ people, greeting }) =>
  <ul>{people.map(person =>
    <li key={person}>{greeting} {`${person}`}!</li>
  )}</ul>
);
<Greetings people="user.friends" greeting="Hello"/>

License

©2018–present Ruben Verborgh, MIT License.