Skip to content

Commit

Permalink
docs: new github callouts, design choices
Browse files Browse the repository at this point in the history
  • Loading branch information
JulianCataldo committed Dec 7, 2023
1 parent 0c0400b commit b03f4b1
Show file tree
Hide file tree
Showing 6 changed files with 399 additions and 25 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ dist-ssr
# Editor directories and files
.vscode/*
!.vscode/extensions.json
!.vscode/settings.json
.idea
.DS_Store
*.suo
Expand Down
9 changes: 8 additions & 1 deletion .vscode/extensions.json
Original file line number Diff line number Diff line change
@@ -1 +1,8 @@
{}
{
"recommendations": [
"stylelint.vscode-stylelint",
"dbaeumer.vscode-eslint",
"runem.lit-plugin",
"esbenp.prettier-vscode"
]
}
21 changes: 21 additions & 0 deletions .vscode/settings.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
{
"cssVariables.lookupFiles": [
"**/*.css",
"**/*.scss",
"**/*.sass",
"**/*.less",
"packages/shoelace/node_modules/@shoelace-style/shoelace/dist/themes/dark.css",
// "packages/shoelace/node_modules/@shoelace-style/shoelace/dist/themes/light.css",

"packages/spectrum/node_modules/@spectrum-web-components/styles/spectrum-scale-large.css",
"packages/spectrum/node_modules/@spectrum-web-components/styles/spectrum-theme-dark.css",
"packages/spectrum/node_modules/@spectrum-web-components/styles/typography.css",
"packages/spectrum/node_modules/@spectrum-web-components/styles/core-global.css",
"packages/spectrum/node_modules/@spectrum-web-components/styles/spectrum-core-global.css"
],
"markdown.extension.toc.levels": "2..6",

// Unused
"html.customData": ["./vscode.html-custom-data.json"],
"css.customData": ["./vscode.css-custom-data.json"]
}
52 changes: 36 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# 📝  JSON Schema Form Element

[![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://www.webcomponents.org/element/@jsfe/form)
[![ISC License](https://img.shields.io/npm/l/@jsfe/form)](./LICENSE)
[![ISC License](https://img.shields.io/npm/l/@jsfe/form)](./LICENSE)
![Downloads](https://img.shields.io/npm/dt/@jsfe/form)
[![GitHub](https://img.shields.io/badge/Repository-222222?logo=github)](https://github.com/json-schema-form-element/jsfe)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://makeapullrequest.com)
[![TypeScript](https://img.shields.io/badge/TypeScript-333333?logo=typescript)](http://www.typescriptlang.org/)
Expand Down Expand Up @@ -50,7 +51,7 @@ Comes with Shoelace 2 and Google Material 3 web components libraries or barebone
Swap built-in components with your own, or add custom widget thanks to [UI schema](#schema) definitions. -->

> **Warning**
> [!CAUTION]
> Not for production.
> Expect the doc. to be not in sync. with the actual released code.
Expand Down Expand Up @@ -133,7 +134,7 @@ Jump to [**UI libraries**](#component-libraries):
- [Usage](#usage)
- [Installation](#installation)
- [UI Libraries](#ui-libraries)
- [Implementation](#implementation)
- [Implementations](#implementations)
- [All examples](#all-examples)
- [Pure HTML with CDN](#pure-html-with-cdn)
- [TypeScript (no framework)](#typescript-no-framework)
Expand All @@ -149,6 +150,7 @@ Jump to [**UI libraries**](#component-libraries):
- [Component libraries](#component-libraries)
- [Shoelace](#shoelace)
- [Custom widgets](#custom-widgets)
- [Design choices](#design-choices)
- [Validation](#validation)
- [Schema massaging](#schema-massaging)
- [Custom Elements Manifests](#custom-elements-manifests)
Expand Down Expand Up @@ -560,6 +562,8 @@ items:
### Installation
**This is for the bare package**. You'll have to bring all the widgets yourself.
```sh
npm i @jsfe/form
# or
Expand All @@ -572,7 +576,7 @@ yarn add @jsfe/form

See [examples/src/pages/flavored.astro](https://github.com/json-schema-form-element/examples/blob/main/src/pages/flavored.astro)

Alternatively:
_Alternatively_:

```
npm install @jsfe/shoelace
Expand Down Expand Up @@ -601,9 +605,9 @@ import '@shoelace-style/shoelace/dist/themes/dark.css';

See also the [CSS section](#CSS).

### Implementation
### Implementations

> **Warning**
> [!CAUTION]
> This project is new, API is subject to changes
#### All examples
Expand Down Expand Up @@ -855,15 +859,15 @@ Please file an issue if an info is wrong or missing.
Each implementation examples are trying to show off the most type-safe way to use JSFE, with the least trade-offs.

Using it more **declaratively** or **imperatively** is up to you, your framework ability and you coding style.
Bot usages are valid and can be mixed. Typically when you want to use the schema elsewhere in your app., or
Both usages are valid and can be mixed. Typically when you want to use the schema elsewhere in your app., or
when your callbacks are getting too beefy, you'll better extract them from templates.

Generally, imperative usage get perfect TypeScript support (you just handle the class), whereas declaratively, you'll have
to deal with various template languages limitations (this is an universal problem).

## Component libraries

> **Warning**
> [!IMPORTANT]
> Before you dive in, here is some context about Web Components libraries support with JSFE.
Whereas you are starting from scratch or you want to integrate declarative forms in
Expand All @@ -880,10 +884,10 @@ Why so?
- Keep an eye on converging practices across vendors.
- Ensure that _JSFE_ remains not to tied with _Shoelace_ way of things (which is already quite thin, relatively).
- Be able to swap out built-ins for custom widgets on a pinch, when needed.
- Borrow valuable ideas from others libraries and re-implement them in Shoelace when lacking.
- Borrow valuable ideas from others libraries and re-implement them with Shoelace bits when lacking.

> **Warning**
> I will not maintain the full spectrum of _JSFE_ widgets, accross all libraries!
> [!WARNING]
> I will not maintain the **full spectrum** of _JSFE_ widgets, accross all libraries!
But I will do my best to provide all the hooks you need, thanks to an _agnostic_ and _type-safe_ API,
smoothening some peculiarities.
Expand Down Expand Up @@ -938,6 +942,20 @@ That's why it's the very first library implemented in _JSFE_.

### Custom widgets

#### Design choices

You might have noticed that _JSFE_ is not using Custom Elements as a medium for injecting widgets.
First prototypes where using them, but I've had troubles regarding the parent form element awareness about its children.
E.g. with Shoelace, inputs weren't responding well with form validation, the <kbd>ENTER</kbd> key for submit, etc.
I'm sure there are ways to circumvent those hassles (forwarding events…), I tried, but for now it's not a priority, as that might affect various UI libs in different ways.

Moreover, Web Components users are eager to see [Custom Registries](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry) becoming maintream.
That will make the process of overriding widgets much more flexible.

For now, using Lit's `TemplateResult` (returning an `html` snippet from a function) is straight-forward, however there are some trade-offs; it's a state-less function, no CSS scoping, lit-tied, etc.

Ultimately, goal is to make JSFE fully modular and agnostic, by using well-defined Custom Elements, for each individual form control.

🚧……🚧

<!-- OLD -->
Expand All @@ -962,7 +980,7 @@ Mapping between schema and “real” fields happens at the `HTMLElement` level,

## Validation

You're responsible to hook-up additional / more advanced validation with, e.g, AJV.
You're responsible to hook-up additional / more advanced validation with, e.g, AJV.
HTML native validation is already quite powerful, but you might want to do
your own wizardry.
Note that client-validation is more for user experience,
Expand All @@ -977,8 +995,8 @@ JSFE doesn't bundle, dereference, nor it is fetching remote
schemas.
Doing so would add a huge payload to the library, and you might certainly have already those tools at hand somewhere in your stack.
Only thing it does is resolving [JSON references](https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03), pointing to **local definitions** only.
Implementation is quite simple, and because this is a much needed feature for DRY-ness, recursivity…
Hopefully it's easy to bring in an advanced parser along, like the [`json-schema-ref-parser`](https://github.com/APIDevTools/json-schema-ref-parser).
This is because implementation is relatively trivial, without much code, and that's a much needed feature for DRY-ness, recursivity…
Hopefully it's easy to bring in an full-featured parser / resolver along, like the [`json-schema-ref-parser`](https://github.com/APIDevTools/json-schema-ref-parser).

## Custom Elements Manifests

Expand All @@ -1003,15 +1021,17 @@ With internal dependencies included, minus peer dependencies (UI libs.):
</div>

`@jsfe/form` contains the base class from which all other packages extends themselves from.
You don't need to install it, unless you want to provide widgets and styles from scratch.
**You don't need to install it**, unless you want to provide widgets and styles from scratch.
If you just want to override _some_ of the flavored components, `@jsfe/<theme>` packages are handy starters.

`@jsfe/types` contains everything for assisting your own widgets authoring.
It's re-exported from every package so you don't need to install it on your own.

### _Next_ versions

You can try nightly builds from the `next` branch like this: `npm i @jsfe/<package>@next`.
> [!TIP]
> You can try the upcoming release from the [`next` branch](https://github.com/json-schema-form-element/jsfe/tree/next) like this:
> `npm i @jsfe/<package>@next`.
## Experimental features

Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@
"eslint-plugin-tsdoc": "^0.2.17",
"lerna": "^8.0.0",
"prettier": "^3.1.0",
"remark": "^15.0.1",
"sort-package-json": "^2.6.0",
"stylelint": "^15.11.0",
"stylelint-config-prettier": "^9.0.5",
Expand Down
Loading

0 comments on commit b03f4b1

Please sign in to comment.