feat: solid-primitives-parser

README.md

@@ -6,7 +6,7 @@
 
 [![pnpm](https://img.shields.io/badge/maintained%20with-pnpm-cc00ff.svg?style=for-the-badge&logo=pnpm)](https://pnpm.io/)
 [![turborepo](https://img.shields.io/badge/built%20with-turborepo-cc00ff.svg?style=for-the-badge&logo=turborepo)](https://turborepo.org/)<!-- INSERT-NPM-DOWNLOADS-BADGE:START -->
-[![combined-downloads](https://img.shields.io/endpoint?style=for-the-badge&url=https://combined-npm-downloads.deno.dev/@solid-primitives/analytics,@solid-primitives/broadcast-channel,@solid-primitives/context,@solid-primitives/devices,@solid-primitives/event-dispatcher,@solid-primitives/event-props,@solid-primitives/fetch,@solid-primitives/fullscreen,@solid-primitives/gestures,@solid-primitives/i18n,@solid-primitives/idle,@solid-primitives/input-mask,@solid-primitives/keyed,@solid-primitives/permission,@solid-primitives/platform,@solid-primitives/scheduled,@solid-primitives/script-loader,@solid-primitives/selection,@solid-primitives/share,@solid-primitives/storage,@solid-primitives/timer,@solid-primitives/tween,@solid-primitives/utils,@solid-primitives/websocket,@solid-primitives/workers)](https://dash.deno.com/playground/combined-npm-downloads)
+[![combined-downloads](https://img.shields.io/endpoint?style=for-the-badge&url=https://combined-npm-downloads.deno.dev/@solid-primitives/analytics,@solid-primitives/broadcast-channel,@solid-primitives/context,@solid-primitives/devices,@solid-primitives/event-dispatcher,@solid-primitives/event-props,@solid-primitives/fetch,@solid-primitives/fullscreen,@solid-primitives/gestures,@solid-primitives/i18n,@solid-primitives/idle,@solid-primitives/input-mask,@solid-primitives/jsx-parser,@solid-primitives/keyed,@solid-primitives/permission,@solid-primitives/platform,@solid-primitives/scheduled,@solid-primitives/script-loader,@solid-primitives/selection,@solid-primitives/share,@solid-primitives/storage,@solid-primitives/timer,@solid-primitives/tween,@solid-primitives/utils,@solid-primitives/websocket,@solid-primitives/workers)](https://dash.deno.com/playground/combined-npm-downloads)
 <!-- INSERT-NPM-DOWNLOADS-BADGE:END -->
 
 A project that strives to develop high-quality, community contributed Solid primitives. All utilities are well tested and continuously maintained. Every contribution to the repository is checked for quality and maintained to the highest degree of excellence. The ultimate goal is to extend Solid's primary and secondary primitives with a set of tertiary primitives.
@@ -66,6 +66,7 @@ The goal of Solid Primitives is to wrap client and server side functionality to
 |[event-dispatcher](https://github.com/solidjs-community/solid-primitives/tree/main/packages/event-dispatcher#readme)|[![STAGE](https://img.shields.io/endpoint?style=for-the-badge&label=&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-0.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)|[createEventDispatcher](https://github.com/solidjs-community/solid-primitives/tree/main/packages/event-dispatcher#createeventdispatcher)|[![SIZE](https://img.shields.io/bundlephobia/minzip/@solid-primitives/event-dispatcher?style=for-the-badge&label=)](https://bundlephobia.com/package/@solid-primitives/event-dispatcher)|[![VERSION](https://img.shields.io/npm/v/@solid-primitives/event-dispatcher?style=for-the-badge&label=)](https://www.npmjs.com/package/@solid-primitives/event-dispatcher)|
 |[i18n](https://github.com/solidjs-community/solid-primitives/tree/main/packages/i18n#readme)|[![STAGE](https://img.shields.io/endpoint?style=for-the-badge&label=&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-3.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)|[createI18nContext](https://github.com/solidjs-community/solid-primitives/tree/main/packages/i18n#createi18ncontext)<br />[useI18n](https://github.com/solidjs-community/solid-primitives/tree/main/packages/i18n#usei18n)|[![SIZE](https://img.shields.io/bundlephobia/minzip/@solid-primitives/i18n?style=for-the-badge&label=)](https://bundlephobia.com/package/@solid-primitives/i18n)|[![VERSION](https://img.shields.io/npm/v/@solid-primitives/i18n?style=for-the-badge&label=)](https://www.npmjs.com/package/@solid-primitives/i18n)|
 |[immutable](https://github.com/solidjs-community/solid-primitives/tree/main/packages/immutable#readme)|[![STAGE](https://img.shields.io/endpoint?style=for-the-badge&label=&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-2.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)|[List of functions](https://github.com/solidjs-community/solid-primitives/tree/main/packages/immutable#list-of-functions)|[![SIZE](https://img.shields.io/bundlephobia/minzip/@solid-primitives/immutable?style=for-the-badge&label=)](https://bundlephobia.com/package/@solid-primitives/immutable)|[![VERSION](https://img.shields.io/npm/v/@solid-primitives/immutable?style=for-the-badge&label=)](https://www.npmjs.com/package/@solid-primitives/immutable)|
+|[jsx-parser](https://github.com/solidjs-community/solid-primitives/tree/main/packages/jsx-parser#readme)|[![STAGE](https://img.shields.io/endpoint?style=for-the-badge&label=&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-0.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)|[createJSXParser](https://github.com/solidjs-community/solid-primitives/tree/main/packages/jsx-parser#createjsxparser)|[![SIZE](https://img.shields.io/bundlephobia/minzip/@solid-primitives/jsx-parser?style=for-the-badge&label=)](https://bundlephobia.com/package/@solid-primitives/jsx-parser)|[![VERSION](https://img.shields.io/npm/v/@solid-primitives/jsx-parser?style=for-the-badge&label=)](https://www.npmjs.com/package/@solid-primitives/jsx-parser)|
 |[map](https://github.com/solidjs-community/solid-primitives/tree/main/packages/map#readme)|[![STAGE](https://img.shields.io/endpoint?style=for-the-badge&label=&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-2.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)|[ReactiveMap](https://github.com/solidjs-community/solid-primitives/tree/main/packages/map#reactivemap)<br />[ReactiveWeakMap](https://github.com/solidjs-community/solid-primitives/tree/main/packages/map#reactiveweakmap)|[![SIZE](https://img.shields.io/bundlephobia/minzip/@solid-primitives/map?style=for-the-badge&label=)](https://bundlephobia.com/package/@solid-primitives/map)|[![VERSION](https://img.shields.io/npm/v/@solid-primitives/map?style=for-the-badge&label=)](https://www.npmjs.com/package/@solid-primitives/map)|
 |[pagination](https://github.com/solidjs-community/solid-primitives/tree/main/packages/pagination#readme)|[![STAGE](https://img.shields.io/endpoint?style=for-the-badge&label=&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-0.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)|[createPagination](https://github.com/solidjs-community/solid-primitives/tree/main/packages/pagination#createpagination)|[![SIZE](https://img.shields.io/bundlephobia/minzip/@solid-primitives/pagination?style=for-the-badge&label=)](https://bundlephobia.com/package/@solid-primitives/pagination)|[![VERSION](https://img.shields.io/npm/v/@solid-primitives/pagination?style=for-the-badge&label=)](https://www.npmjs.com/package/@solid-primitives/pagination)|
 |[platform](https://github.com/solidjs-community/solid-primitives/tree/main/packages/platform#readme)|[![STAGE](https://img.shields.io/endpoint?style=for-the-badge&label=&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-1.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)|[List of variables](https://github.com/solidjs-community/solid-primitives/tree/main/packages/platform#list-of-variables)|[![SIZE](https://img.shields.io/bundlephobia/minzip/@solid-primitives/platform?style=for-the-badge&label=)](https://bundlephobia.com/package/@solid-primitives/platform)|[![VERSION](https://img.shields.io/npm/v/@solid-primitives/platform?style=for-the-badge&label=)](https://www.npmjs.com/package/@solid-primitives/platform)|

packages/jsx-parser/LICENSE

@@ -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.

packages/jsx-parser/README.md

@@ -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)

packages/jsx-parser/dev/index.html

@@ -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>

packages/jsx-parser/dev/index.tsx

@@ -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")!);

packages/jsx-parser/dev/vite.config.ts

@@ -0,0 +1,2 @@
+import { viteConfig } from "../../../configs/vite.config";
+export default viteConfig;

packages/jsx-parser/package.json

@@ -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 <[email protected]>",
+  "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"
+  }
+}