Skip to content

Commit

Permalink
Graduate React, Task, and Context in v3 documentation (#1208)
Browse files Browse the repository at this point in the history
* graduate react, task, and context in documentation

* remove react from labs in v3 navigation

* remove labs disclaimer from react docs

* remove labs mentions from context docs
  • Loading branch information
AndrewJakubowicz authored Oct 6, 2023
1 parent f5c9bc1 commit 5b67499
Show file tree
Hide file tree
Showing 4 changed files with 27 additions and 77 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -280,7 +280,7 @@ Asynchronous tasks, such as long running computations or network I/O, typically

Controllers are a great way to bundle task execution and state to make it easy to use inside a component. A task written as a controller usually has inputs that a host can set, and outputs that a host can render.

`@lit-labs/task` contains a generic `Task` controller that can pull inputs from the host, execute a task function, and render different templates depending on the task state.
`@lit/task` contains a generic `Task` controller that can pull inputs from the host, execute a task function, and render different templates depending on the task state.

You can use `Task` to create a custom controller with an API tailored for your specific task. Here we wrap `Task` in a `NamesController` that can fetch one of a specified list of names from a demo REST API. `NameController` exposes a `kind` property as an input, and a `render()` method that can render one of four templates depending on the task state. The task logic, and how it updates the host, are abstracted from the host component.

Expand All @@ -295,4 +295,4 @@ You can use `Task` to create a custom controller with an API tailored for your s
## See also

* [Reactive update cycle](/docs/v3/components/lifecycle/#reactive-update-cycle)
* [@lit-labs/task](https://www.npmjs.com/package/@lit-labs/task)
* [@lit/task](https://www.npmjs.com/package/@lit/task)
41 changes: 19 additions & 22 deletions packages/lit-dev-content/site/docs/v3/data/context.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,16 @@ eleventyNavigation:
key: Context
parent: Managing Data
order: 1
labs: true
versionLinks:
v2: data/context/
---

{% labs-disclaimer %}

Context is a way of making data available to entire component subtrees without having to manually bind properties to every component. The data is "contextually" available, such that ancestor elements in between a provider of data and consumer of data aren't even aware of it.

Lit's context implementation is part of [Lit Labs](/docs/v3/libraries/labs/) and available in the `@lit-labs/context` package:
Lit's context implementation is available in the `@lit/context` package:

```bash
npm i @lit-labs/context
npm i @lit/context
```

Context is useful for data that needs to be consumed by a wide variety and large number of components - things like an app's data store, the current user, a UI theme - or when data-binding isn't an option, such as when an element needs to provide data to its light DOM children.
Expand All @@ -29,7 +26,7 @@ Using context involves a _context object_ (sometimes called a key), a _provider_

Context definition (`logger-context.ts`):
```ts
import {createContext} from '@lit-labs/context';
import {createContext} from '@lit/context';
import type {Logger} from 'my-logging-library';
export type {Logger} from 'my-logging-library';
export const loggerContext = createContext<Logger>('logger');
Expand All @@ -38,7 +35,7 @@ export const loggerContext = createContext<Logger>('logger');
Provider:
```ts
import {LitElement, property, html} from 'lit';
import {provide} from '@lit-labs/context';
import {provide} from '@lit/context';

import {Logger} from 'my-logging-library';
import {loggerContext} from './logger-context.js';
Expand All @@ -58,7 +55,7 @@ class MyApp extends LitElement {
Consumer:
```ts
import {LitElement, property} from 'lit';
import {consume} from '@lit-labs/context';
import {consume} from '@lit/context';

import {type Logger, loggerContext} from './logger-context.js';

Expand All @@ -83,7 +80,7 @@ This protocol enables interoperability between elements (or even non-element cod

The Context Protocol is based on DOM events. A consumer fires a `context-request` event that carries the context key that it wants, and any element above it can listen for the `context-request` event and provide data for that context key.

`@lit-labs/context` implements this event-based protocol and makes it available via a few reactive controllers and decorators.
`@lit/context` implements this event-based protocol and makes it available via a few reactive controllers and decorators.

### Context Objects

Expand Down Expand Up @@ -157,7 +154,7 @@ Usually it's best to use a globally unique context object. Symbols are one of th

### Providing a context

There are two ways in `@lit-labs/context` to provide a context value: the ContextProvider controller and the `@provide()` decorator.
There are two ways in `@lit/context` to provide a context value: the ContextProvider controller and the `@provide()` decorator.

#### `@provide()`

Expand All @@ -167,7 +164,7 @@ Decorate a property with `@provide()` and give it the context key:
```ts
import {LitElement, html} from 'lit';
import {property} from 'lit/decorators.js';
import {provide} from '@lit-labs/context';
import {provide} from '@lit/context';
import {myContext, MyData} from './my-context.js';

class MyApp extends LitElement {
Expand Down Expand Up @@ -204,7 +201,7 @@ Making a context property public lets an element provide a public field to its c

```ts
import {LitElement, html} from 'lit';
import {ContextProvider} from '@lit-labs/context';
import {ContextProvider} from '@lit/context';
import {myContext, MyData} from './my-context.js';

export class MyApp extends LitElement {
Expand Down Expand Up @@ -232,7 +229,7 @@ The `@consume()` decorator is the easiest way to consume a value if you're using
Decorate a property with `@consume()` and give it the context key:
```ts
import {LitElement, html} from 'lit';
import {consume} from '@lit-labs/context';
import {consume} from '@lit/context';
import {myContext, MyData} from './my-context.js';

class MyElement extends LitElement {
Expand All @@ -249,7 +246,7 @@ ContextConsumer is a reactive controller that manages dispatching the `context-r

```ts
import {LitElement, property} from 'lit';
import {ContextConsumer} from '@lit-labs/context';
import {ContextConsumer} from '@lit/context';
import {Logger, loggerContext} from './logger.js';

export class MyElement extends LitElement {
Expand Down Expand Up @@ -335,7 +332,7 @@ Creates a typed Context object
**Import**:

```ts
import {property} from '@lit-labs/context';
import {property} from '@lit/context';
```

**Signature**:
Expand Down Expand Up @@ -374,7 +371,7 @@ A property decorator that adds a ContextConsumer controller to the component whi
**Import**:

```ts
import {provide} from '@lit-labs/context';
import {provide} from '@lit/context';
```

**Signature**:
Expand All @@ -390,7 +387,7 @@ A property decorator that adds a ContextConsumer controller to the component whi
**Import**:

```ts
import {consume} from '@lit-labs/context';
import {consume} from '@lit/context';
```

**Signature**:
Expand All @@ -408,7 +405,7 @@ A ReactiveController which adds context provider behavior to a custom element by
**Import**:

```ts
import {ContextProvider} from '@lit-labs/context';
import {ContextProvider} from '@lit/context';
```

**Constructor**:
Expand All @@ -435,7 +432,7 @@ A ReactiveController which adds context consuming behavior to a custom element b
**Import**:

```ts
import {ContextConsumer} from '@lit-labs/context';
import {ContextConsumer} from '@lit/context';
```

**Constructor**:
Expand Down Expand Up @@ -465,7 +462,7 @@ A ContextRoot can be used to gather unsatisfied context requests and re-dispatch
**Import**:

```ts
import {ContextRoot} from '@lit-labs/context';
import {ContextRoot} from '@lit/context';
```

**Constructor**:
Expand All @@ -490,7 +487,7 @@ The event fired by consumers to request a context value. The API and behavior of
**Import**:

```ts
import {ContextRequestEvent} from '@lit-labs/context';
import {ContextRequestEvent} from '@lit/context';
```

The `context-request` bubbles and is composed.
Expand Down Expand Up @@ -518,7 +515,7 @@ This callback can be called multiple times by context providers as the requested
**Import**:

```ts
import {type ContextCallback} from '@lit-labs/context';
import {type ContextCallback} from '@lit/context';
```

**Signature**:
Expand Down
13 changes: 5 additions & 8 deletions packages/lit-dev-content/site/docs/v3/frameworks/react.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,11 @@ eleventyNavigation:
key: React
parent: Frameworks
order: 1
labs: true
versionLinks:
v2: frameworks/react/
---

{% labs-disclaimer %}

The [@lit-labs/react](https://github.com/lit/lit/tree/main/packages/labs/react) package provides utilities to create React wrapper components for web components, and custom hooks from [reactive controllers](../../composition/controllers/).
The [@lit/react](https://github.com/lit/lit/tree/main/packages/labs/react) package provides utilities to create React wrapper components for web components, and custom hooks from [reactive controllers](../../composition/controllers/).

The React component wrapper enables setting properties on custom elements (instead of just attributes), mapping DOM events to React-style callbacks, and enables correct type-checking in JSX by TypeScript.

Expand All @@ -27,7 +24,7 @@ For instance, React assumes that all JSX properties map to HTML element attribut

React is working on fixes to these issues, but in the meantime, our wrappers take care of setting properties and listening to events for you.

The `@lit-labs/react` package provides two main exports:
The `@lit/react` package provides two main exports:

- `createComponent()` creates a React component that _wraps_ an existing web component. The wrapper allows you to set props on the component and add event listeners to the component like you would any other React component.

Expand All @@ -43,7 +40,7 @@ Import `React`, a custom element class, and `createComponent`.

```js
import React from 'react';
import {createComponent} from '@lit-labs/react';
import {createComponent} from '@lit/react';
import {MyElement} from './my-element.js';

export const MyElementComponent = createComponent({
Expand Down Expand Up @@ -129,7 +126,7 @@ The `EventName` type is a string that takes an event interface as a type paramet
```ts

import React from 'react';
import {createComponent} from '@lit-labs/react';
import {createComponent} from '@lit/react';
import {MyElement, type EventName} from './my-element.js';

export const MyElementComponent = createComponent({
Expand Down Expand Up @@ -177,7 +174,7 @@ instead of functions with hidden state.

```jsx
import React from 'react';
import {useController} from '@lit-labs/react/use-controller.js';
import {useController} from '@lit/react/use-controller.js';
import {MouseController} from '@example/mouse-controller';

// Write a custom React hook function:
Expand Down
46 changes: 1 addition & 45 deletions packages/lit-dev-content/site/docs/v3/libraries/labs.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Lit Labs is an umbrella for Lit packages under development that we are actively
- Lit Labs projects are published under the `@lit-labs` npm scope.
- Breaking changes are likely to occur more frequently than in non-labs packages, but they will still respect standard semantic versioning guildelines and all changes will be published to the CHANGELOG files.
- While we strive to address all bugs in a timely fashion, bugs in non-labs projects typically receive higher priority than bugs in labs projects.
- When a Lit Labs project is ready to graduate out of labs, we'll begin publishing it under the `@lit` scope. (For example, `@lit-labs/task` might graduate to `@lit/task`.) Once a package graduates, its first version under the `@lit` scope will match that of the latest in `@lit-labs`—but only the `@lit` version will receive subsequent updates.
- When a Lit Labs project is ready to graduate out of labs, we'll begin publishing it under the `@lit` scope. (For example, `@lit-labs/task` graduated to `@lit/task`.) Once a package graduates, its first version under the `@lit` scope will match that of the latest in `@lit-labs`—but only the `@lit` version will receive subsequent updates.
- We may decide to deprecate a Lit Labs project. In such cases, we will notify the community, and a deprecation warning will be added to the npm package. The deprecated package will receive bug fix support for at least 6 months. A record of historical labs packages will be kept on this page.

Feedback is currently being solicited on the following Labs packages:
Expand All @@ -30,37 +30,6 @@ Feedback is currently being solicited on the following Labs packages:
<thead><tr><th>Package</th><th>Description</th><th>Links</th></tr></thead>
<tbody>
<tr class="subheading"><td colspan=3>Near graduation</td></tr>
<tr>
<td>

[context](https://www.npmjs.com/package/@lit-labs/context)

</td>
<td>

A package containing controllers and decorators for using the [Context Protocol](https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md).

</td>
<td class="labs-table-links">

[📄&nbsp;Docs](/docs/v3/data/context/ "Docs")<br>[💬&nbsp;Feedback](https://github.com/lit/lit/discussions/3302 "Feedback")<br>[🐞&nbsp;Issues](https://github.com/lit/lit/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+%5Blabs%2Fcontext%5D "Issues")

</td>
</tr>

<tr>
<td>

[react](https://www.npmjs.com/package/@lit-labs/react)

</td>
<td>React integration helpers for custom elements and reactive controllers.</td>
<td class="labs-table-links">

[📄&nbsp;Docs](https://github.com/lit/lit/tree/main/packages/labs/react#readme "Docs")<br>[💬&nbsp;Feedback](https://github.com/lit/lit/discussions/3358 "Feedback")<br>[🐞&nbsp;Issues](https://github.com/lit/lit/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+%5Blabs%2Freact%5D "Issues")

</td>
</tr>

<tr>
<td>
Expand Down Expand Up @@ -142,19 +111,6 @@ A plugin for [Eleventy](https://www.11ty.dev) that pre-renders Lit components at
</td>
</tr>

<tr>
<td>

[task](https://www.npmjs.com/package/@lit-labs/task)

</td>
<td>A reactive controller for handling asynchronous tasks.</td>
<td class="labs-table-links">

[📄&nbsp;Docs](https://github.com/lit/lit/tree/main/packages/labs/task#readme "Docs")<br>[💬&nbsp;Feedback](https://github.com/lit/lit/discussions/3361 "Feedback")<br>[🐞&nbsp;Issues](https://github.com/lit/lit/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+%5Blabs%2Ftask%5D "Issues")

</td>
</tr>

<tr>
<td>
Expand Down

0 comments on commit 5b67499

Please sign in to comment.