joist-framework/joist

A small (~2kb) library to help with the creation of web components and web component based applications

Joist

Web components are awesome! Joist is a set of small libraries designed to add the bare minimum to web components to make you as productive as possible. The entire project started years ago when I made my first attempt at bringing dependency injection (@joist/di) to Custom Elements as a way to share state between them. Along the way, several other packages were added to solve different challenges.

When you have to integrate with many different applications, many different frameworks with many different technologies you need a toolkit to help. From SalesForce to ServiceNow to React you need to write JavaScript/TypeScript and you need tools to help.

This toolkit is here to help provide just the functionality you need and nothing more. Use with Lit, FAST, Vanilla WC, Node, wherever you find yourself.

Packages

Package	Description
@joist/di	IOC container. Share state between elements
@joist/element	utilities for custom elements
@joist/observable	Observe changes to class properties

joist's Issues

@joist/di: lint rule for inject array not matching Injected types.

It would be nice if there was a lint rule that could detect if the array of injected dependencies didn't match the arguments passed to the constructor. This would only work with typescript.

For example:

class Foo {}
class Bar {}

// This should throw an error since Foo != Bar
class Baz {
  static inject = [Foo]; 

  constructor(foo: Injected<Bar>) {}
}

Improve Router Docs

@joist/di: clear local cached instances on disconnect and connect

while connectedCallback and disconnectedCallback are use for setup and teardown, they are also called when elements are MOVED. Since this could mean a potential change in scope local instances should be reset

Dev Tools

Joist should have a service available so that we can get errors and property autocomplete in IDEs.

SSR

I have a prototype branch that leverages declarative shadow dom to render web components serverside. What it does is recursively look through a document and add the template for the shadow root. This should include a prepackaged vite plugin as well. The vite plugin should be responsible for injecting scripts (if available) and discovering html documents to act as entry points.

Is my counter idiomatic?

Hi!

@Nevraeka contacted us to had joist to our platform (WebComponents.dev) and also to the next update of All the ways to make a web component.

I built this https://webcomponents.dev/edit/1vBcIqaZeu8M14HFOlYO
Is that correct? Is that how you would write it?

Cheers!

Allow for easier debug of dependency graph

To help make it easier to debug injectors and their dependencies there should be an optional API that will describe how a particular series was resolved.

Initial thought it is export an additional injectDebug() function. (To make it tree shakeable)

This function would log the dependency tree for the injected service.

Cc @Phoscur

Feature: construct-able stylesheets

When construct-able stylesheets are available they should be used rather then inlining in final template result.

Styles

@component({
  styles: [`
    :host {
      display: block
    }
  `],
  render({ host }) {
    host.innerHTML = 'Hello World'
  }
})
class MyElements extends JoistElement {}

Better test coverage of router

The router is the least covered in terms of testing. Needs more!

runtime property validation

It might be nice to have a way of validating properties at runtime.
For example throwing an error if a property is set with an incorrect value. This could be handled manually in onPropChanges or custom setters. So it may just bloat the api. If we DO think this is a worthwhile addition we could also add built in validators under @joist/component/prop-validators

class MyElement extends JoistElement {
  @property(val => !!val.length)
  public name: string;
}

new MyElement().name = 100; // Would throw error

@joist/di: implement lint fix to autofill injected services

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Improve Component and Application Docs

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Improve unit tests for component styles

Batch property changes

at the moment onPropChanges is called on every property change. Ideally it would batch these so that if two properties are set one right after the other onPropChanges is only called once.

Create a non constructable ProviderToken

At the moment we assume that all tokens are constructable. This works for 99% of use cases. There are often times where you might want to inject someone other than an object or want to require a specific definition.

An 'InjectionToken' will define a specific symbol to be used in the injection and define the type that the symbol should resolve to.

The injector would return an error if it is unable to find a provider for the particular token.

3.0

This ticket will be a checklist for all 3.0 features.

• refactor observable
• investigate decorator based inject.
• refactor shadow
• refactor and simplify build tooling and output (wireit)
• di: default to provideInRoot behavior

Observable can be made much much simpler now that we can hook into two parts of the class life cycle. First we can remove the overall observeable decorator and only use the individual observe one.

publish bundle for compat with unpkg

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Optional shadow dom.

Shadow dom gives us native encapsulation and content projection but at the moment has some difficulties with screen readers. Because of this shadow dom should be optional. This will mean fixing an issue where the template is applied in the constructor rather than connectedCallback

Add option for inject to require a manually defined dependency.

Allow the inject function to require a provider to be defined. This would mean no fall back to the global injector.

inject(MyService, { fallback: false })

Cc @Phoscur

Cannot register element before dom renders with @attr

Describe the bug
A clear and concise description of what the bug is.

To Reproduce
Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: [e.g. iOS]
• Browser [e.g. chrome, safari]
• Version [e.g. 22]

Smartphone (please complete the following information):

• Device: [e.g. iPhone6]
• OS: [e.g. iOS8.1]
• Browser [e.g. stock browser, safari]
• Version [e.g. 22]

Additional context
Add any other context about the problem here.

Feature: Router

There should be a small simple router. The router should
[] allow child routes
[] should be easy to use with lit-kit but should be useable outside of the framework

Allow handlers to use pattern to match actions.

class MyElement extends JoistElement {
  @handle("*") handlesAll() {}

  @handle("foo-*") handlesThatStartsWithFoo() {}
}

Custom Element definition order matters

Describe the bug
It's not directly obvious that custom element parents need to be defined beforehand/in decending order

To Reproduce
Using the example from the readme, vite - reverse the definition order:

customElements.define('my-element', MyElement);
customElements.define('color-ctx', ColorCtx);

Expected behavior
ColorCtx is recognised as parent

Actual behaviour
ColorCtx provider overrides are ignored, because it's not recognised as a parent

Desktop (please complete the following information):

• OS: Windows

Additional context
Took me a few hours debugging in Chromium to find my mistake - can also reproduce in Firefox.

A remark in the readme may be enough to avoid this issue.

Migrate from karma to web-test-runner

Web test runner is a nice alternative with less configuration and would not require a webpack loader.

• port tests to use @open-wc/testing. (away from jasmine)
• replace karma with @web/test-runner

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update dependency @types/node to v20.14.6

Detected dependencies

github-actions

.github/workflows/test.yml

• actions/checkout v4@692973e3d937129bcbf40652eb9f2f61becf3332

npm

integration/counter/package.json

integration/todo/package.json

package.json

• @open-wc/testing ^4.0.0
• @types/mocha ^10.0.1
• @types/node ^20.1.1
• @web/test-runner ^0.18.0
• @web/test-runner-playwright ^0.11.0
• ava ^6.0.0
• browser-sync ^3.0.0
• husky ^9.0.11
• lint-staged ^15.2.2
• prettier ^3.2.5
• tslib 2.6.3
• typescript ^5.3.0
• wireit ^0.14.0

packages/di/package.json

packages/element/package.json

packages/observable/package.json

packages/ssr/package.json

• cheerio ^1.0.0-rc.12

---

• Check this box to trigger a request for Renovate to run again on this repository

Example on how to use this toolkit with Lit

Discussion: should shadowDOM be on by default?

ShadowDOM gives devs some solid features including content projection and style encapsulation.
While these are great style encapsulation can cause some unintended consequences, including but not limited issues with screen readers. In the spirit of wanting to be as good as possible out of the gate should shadowDOM be turned on by default

Decorators should account for ts decorators and the standards proposal

https://coryrylan.com/blog/using-event-decorators-with-lit-element-and-web-components