-
Notifications
You must be signed in to change notification settings - Fork 125
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #276 from bigmistqke/feat/solid-primitives-parser
feat: solid-primitives-parser
- Loading branch information
Showing
11 changed files
with
552 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| MIT License | ||
|
|
||
| Copyright (c) 2021 Solid Primitives Working Group | ||
|
|
||
| Permission is hereby granted, free of charge, to any person obtaining a copy | ||
| of this software and associated documentation files (the "Software"), to deal | ||
| in the Software without restriction, including without limitation the rights | ||
| to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | ||
| copies of the Software, and to permit persons to whom the Software is | ||
| furnished to do so, subject to the following conditions: | ||
|
|
||
| The above copyright notice and this permission notice shall be included in all | ||
| copies or substantial portions of the Software. | ||
|
|
||
| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
| IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
| FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||
| AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||
| LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | ||
| OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | ||
| SOFTWARE. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,134 @@ | ||
| <p> | ||
| <img width="100%" src="https://assets.solidjs.com/banner?type=Primitives&background=tiles&project=JSX%20Parser" alt="Solid Primitives JSX Parser"> | ||
| </p> | ||
|
|
||
| # @solid-primitives/parser | ||
|
|
||
| A primitive to extend the types of values JSX can return. These JSX-elements are named `tokens`. | ||
|
|
||
| - [`createJSXParser`](#createJSXParser) — Provides the tools to create and identify `tokens`: `createToken`, `childrenTokens`, `isToken` and `id`. | ||
| - [`createToken`](#createToken) — Instantiates a `token` associated with the corresponding jsx-parser. | ||
| - [`childrenTokens`](#childrenTokens) — A function similar to Solid's `children()`, but that will only return valid `tokens` created by the corresponding jsx-parser's `createToken` | ||
| - [`isToken`](#isToken) — A function to validate if an element is a `token` created by the corresponding jsx-parser's `createToken` | ||
| - [`id`](#id) — The symbol unique to the corresponding jsx-parser | ||
|
|
||
| ## Installation | ||
|
|
||
| ```bash | ||
| npm install @solid-primitives/jsx-parser | ||
| # or | ||
| yarn add @solid-primitives/jsx-parser | ||
| # or | ||
| pnpm add @solid-primitives/jsx-parser | ||
| ``` | ||
|
|
||
| ## `createJSXParser` | ||
|
|
||
| Provides the tools to create and identify `tokens`. | ||
|
|
||
| ### How to use it | ||
|
|
||
| `createJSXParser` takes an optional id as argument, and returns the following functions `createToken`, `childrenTokens`, `isToken` and the symbol associated with the jsx-parser `id`. | ||
|
|
||
| It also takes as a generic the union of accepted token-types. | ||
|
|
||
| ```tsx | ||
| import { createJSXParser } from "@solid-primitives/jsx-parser"; | ||
|
|
||
| type UnionOfAcceptedTokens = Token1 | Token2 | ... | ||
|
|
||
| const {createToken, childrenTokens, isToken, id} = createJSXParser<UnionOfAcceptedTokens>('parser-example'); | ||
| ``` | ||
|
|
||
| ## `createToken` | ||
|
|
||
| A function to create a `token` associated with the corresponding jsx-parser. | ||
|
|
||
| ### How to use it | ||
|
|
||
| `createToken` takes two callback-arguments: the first callback returns the token, an optional second callback returns a JSXElement. This second callback is used when the token is being rendered by Solid. If the second callback is not present, the following error will be shown instead: `tokens can only be rendered inside a Parser with id ...` | ||
|
|
||
| It takes as generic two types: the props of the associated JSX-element and the return-value of the token. | ||
|
|
||
| ```tsx | ||
| type Props = { | ||
| id: string; | ||
| }; | ||
|
|
||
| type Token = { | ||
| props: Props; | ||
| value: number; | ||
| }; | ||
|
|
||
| const TokenExample = createToken<Props, Token>( | ||
| props => { | ||
| const value = Math.random(); | ||
| return { | ||
| props, | ||
| value | ||
| }; | ||
| }, | ||
| props => { | ||
| return <span>{props.id}</span>; | ||
| } | ||
| ); | ||
| ``` | ||
|
|
||
| This token can then be used as a JSX-element inside your solid-code: | ||
|
|
||
| ```tsx | ||
| const App = () => { | ||
| return <TokenExample id="id" />; | ||
| }; | ||
| ``` | ||
|
|
||
| TokenExample is typed as a JSXElement, this is so TokenExample can be used in JSX without causing type-errors. | ||
|
|
||
| ## `childrenTokens` | ||
|
|
||
| A function similar to Solid's [`children()`](https://www.solidjs.com/docs/latest#children), but that will only return valid `tokens` created by the corresponding jsx-parser's `createToken` | ||
|
|
||
| ### How to use it | ||
|
|
||
| `childrenTokens` takes a callback returning `props.children`, and will return all tokens associated with the corresponding jsx-parser. Just like Solid's `children`, `childrenTokens` will resolve the tokens: multiple `childrenTokens` of the same `props.children` will execute the token-callback multiple times! | ||
|
|
||
| ```tsx | ||
| const tokens = childrenTokens(() => props.children); | ||
| ``` | ||
|
|
||
| ## `isToken` | ||
|
|
||
| A function to validate if a value is a token created by the corresponding jsx-parser, by checking if the value contains the `id`-symbol. | ||
|
|
||
| ### How to use it | ||
|
|
||
| `isToken` takes a value, often this would be a JSXElement. The function returns `false` in case the value is not a token created by the corresponding jsx-parser. In case the value is a token `isToken` returns the value cast to a `token`. | ||
|
|
||
| ```tsx | ||
| const value = props.children[0]; // value is typed as a JSXElement | ||
| const token = isToken(value); | ||
| if (!token) return; | ||
| token; // token is typed as UnionOfAcceptedTokens | ||
| ``` | ||
|
|
||
| ## `id` | ||
|
|
||
| The symbol which is attached to all tokens of the corresponding jsx-parser. This is internally used in `childrenTokens` and `isToken` to validate if a value is a token. | ||
|
|
||
| ### How to use it | ||
|
|
||
| `id` can be used for validation. | ||
|
|
||
| ```tsx | ||
| const value = props.children[0]; | ||
| if (!(id in value)) return; | ||
| const token = value as UnionOfAcceptedTokens; | ||
| ``` | ||
|
|
||
| ## Demo | ||
|
|
||
| TODO | ||
|
|
||
| ## Changelog | ||
|
|
||
| See [CHANGELOG.md](./CHANGELOG.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| <!DOCTYPE html> | ||
| <html lang="en"> | ||
| <head> | ||
| <meta charset="utf-8" /> | ||
| <meta name="viewport" content="width=device-width, initial-scale=1" /> | ||
| <meta name="theme-color" content="#000000" /> | ||
| <title>Solid App</title> | ||
| <style> | ||
| html { | ||
| font-family: "Gill Sans", "Gill Sans MT", Calibri, "Trebuchet MS", sans-serif; | ||
| } | ||
|
|
||
| body { | ||
| padding: 0; | ||
| margin: 0; | ||
| } | ||
|
|
||
| a, | ||
| button { | ||
| cursor: pointer; | ||
| } | ||
| button[disabled] { | ||
| cursor: not-allowed; | ||
| } | ||
| button[aria-current] { | ||
| font-weight: bold; | ||
| background: #222; | ||
| color: #fff; | ||
| } | ||
| * { | ||
| margin: 0; | ||
| } | ||
| </style> | ||
| </head> | ||
|
|
||
| <body> | ||
| <noscript>You need to enable JavaScript to run this app.</noscript> | ||
| <div id="root"></div> | ||
|
|
||
| <script src="/index.tsx" type="module"></script> | ||
| </body> | ||
| </html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| import { Component, JSX, ParentComponent } from "solid-js"; | ||
| import { render } from "solid-js/web"; | ||
| import "uno.css"; | ||
| import { createJSXParser } from "../src"; | ||
|
|
||
| type Props = { | ||
| value: number; | ||
| children?: JSX.Element | JSX.Element[]; | ||
| }; | ||
|
|
||
| const { createToken, childrenTokens } = createJSXParser<{ | ||
| id: "Value" | "Add" | "Subtract"; | ||
| props: Props; | ||
| }>({ name: "calculator" }); | ||
|
|
||
| const Calculator: ParentComponent = props => { | ||
| const tokens = childrenTokens(() => props.children); | ||
|
|
||
| const calculation = () => { | ||
| let result = 0; | ||
| tokens().forEach(token => { | ||
| console.info("token is ", token); | ||
| if (token.id === "Value") { | ||
| result = token.props.value; | ||
| } else if (token.id === "Add") { | ||
| result += token.props.value; | ||
| } else if (token.id === "Subtract") { | ||
| result -= token.props.value; | ||
| } | ||
| console.info("result is", result); | ||
| }); | ||
| return result; | ||
| }; | ||
|
|
||
| return ( | ||
| <div> | ||
| {tokens()} = {calculation()} | ||
| </div> | ||
| ); | ||
| }; | ||
|
|
||
| const Value = createToken( | ||
| (props: Props) => ({ | ||
| props, | ||
| id: "Value" | ||
| }), | ||
| props => <>{props.value}</> | ||
| ); | ||
|
|
||
| const Add = createToken( | ||
| (props: Props) => ({ | ||
| props, | ||
| id: "Add" | ||
| }), | ||
| props => <> + {props.value}</> | ||
| ); | ||
|
|
||
| const Subtract = createToken( | ||
| (props: Props) => ({ | ||
| props, | ||
| id: "Subtract" | ||
| }), | ||
| props => <> - {props.value}</> | ||
| ); | ||
|
|
||
| const App: Component = () => { | ||
| return ( | ||
| <div | ||
| style={{ | ||
| display: "flex", | ||
| "align-items": "center", | ||
| "justify-content": "center", | ||
| height: "100vh" | ||
| }} | ||
| > | ||
| <Calculator> | ||
| <h1>This is a calculator</h1> | ||
| <Value value={1} /> | ||
| <Add value={4} /> | ||
| <Subtract value={2} /> | ||
| </Calculator> | ||
| </div> | ||
| ); | ||
| }; | ||
|
|
||
| render(() => <App />, document.getElementById("root")!); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| import { viteConfig } from "../../../configs/vite.config"; | ||
| export default viteConfig; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| { | ||
| "name": "@solid-primitives/jsx-parser", | ||
| "version": "0.0.1", | ||
| "description": "A primitive to tokenize your solid-components to enable custom parsing.", | ||
| "author": "Vincent Van Dijck <vandijckv@gmail.com>", | ||
| "contributors": [], | ||
| "license": "MIT", | ||
| "homepage": "https://github.com/solidjs-community/solid-primitives/tree/main/packages/parser#readme", | ||
| "repository": { | ||
| "type": "git", | ||
| "url": "git+https://github.com/solidjs-community/solid-primitives.git" | ||
| }, | ||
| "bugs": { | ||
| "url": "https://github.com/solidjs-community/solid-primitives/issues" | ||
| }, | ||
| "primitive": { | ||
| "name": "jsx-parser", | ||
| "stage": 0, | ||
| "list": [ | ||
| "createJSXParser" | ||
| ], | ||
| "category": "Utilities" | ||
| }, | ||
| "keywords": [ | ||
| "solid", | ||
| "primitives", | ||
| "jsx-parser" | ||
| ], | ||
| "private": false, | ||
| "sideEffects": false, | ||
| "files": [ | ||
| "dist" | ||
| ], | ||
| "type": "module", | ||
| "main": "./dist/index.cjs", | ||
| "module": "./dist/index.js", | ||
| "types": "./dist/index.d.ts", | ||
| "browser": {}, | ||
| "exports": { | ||
| "development": { | ||
| "import": { | ||
| "types": "./dist/index.d.ts", | ||
| "default": "./dist/dev.js" | ||
| }, | ||
| "require": "./dist/dev.cjs" | ||
| }, | ||
| "import": { | ||
| "types": "./dist/index.d.ts", | ||
| "default": "./dist/index.js" | ||
| }, | ||
| "require": "./dist/index.cjs" | ||
| }, | ||
| "typesVersions": {}, | ||
| "scripts": { | ||
| "dev": "vite serve dev", | ||
| "build": "jiti ../../scripts/build.ts --dev", | ||
| "test": "vitest -c ../../configs/vitest.config.ts", | ||
| "test:ssr": "pnpm run test --mode ssr" | ||
| }, | ||
| "dependencies": {}, | ||
| "peerDependencies": { | ||
| "solid-js": "^1.6.0" | ||
| } | ||
| } |
Oops, something went wrong.