🎉 Creating project

.eslintrc.cjs

@@ -0,0 +1,53 @@
+module.exports = {
+  env: {
+    browser: true,
+    es2021: true,
+  },
+  extends: [
+    'standard-with-typescript',
+    'plugin:astro/recommended',
+  ],
+  overrides: [
+    {
+      files: ['*.astro'],
+      parser: 'astro-eslint-parser',
+      parserOptions: {
+        parser: '@typescript-eslint/parser',
+        extraFileExtensions: ['.astro'],
+      },
+      rules: {},
+    },
+    {
+      env: {
+        node: true,
+      },
+      files: [
+        '.eslintrc.{js,cjs}',
+        '*.ts',
+      ],
+      parserOptions: {
+        sourceType: 'script',
+      },
+    },
+  ],
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+  },
+  rules: {
+    '@typescript-eslint/comma-dangle': ['error', 'always-multiline'],
+    '@typescript-eslint/member-delimiter-style': [
+      'error',
+      {
+        multiline: {
+          delimiter: 'semi',
+          requireLast: true,
+        },
+      },
+    ],
+    '@typescript-eslint/semi': ['error', 'always'],
+  },
+  ignorePatterns: [
+    'tsconfig.json',
+  ],
+};

.github/workflows/lint.yml

@@ -0,0 +1,27 @@
+name: Linting
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [16.x, 18.x, 20.x]
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm test
+

.gitignore

@@ -0,0 +1,3 @@
+.idea/
+dist/
+node_modules/

LICENSE

@@ -0,0 +1,13 @@
+   Copyright 2019-2023 FusionAuth
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -0,0 +1,222 @@
+# `@fusionauth/astro-components`
+
+This is a set of components developed by FusionAuth while creating [our docs](https://fusionauth.io)
+with [Astro](https://astro.build/).
+
+```mdx
+import { RemoteCode, RemoteValue } from '@fusionauth/astro-components';
+
+# This will render a <Code> component with the contents of that file
+<RemoteCode lang="javascript" url="https://example.com/file.js"/>
+
+# This will extract the username from the JSON file and display it
+You are going to log in as <RemoteValue url="https://example.com/file.json" selector="$.user.username" />.
+```
+
+# Installation
+
+Install it via npm:
+
+```shell
+$ npm install @fusionauth/astro-components
+```
+
+> These components were tested with both versions 2 and 3 of Astro.
+
+# Components
+
+## `<RemoteCode>`
+
+Use this to display a `<Code>`
+component [to provide syntax highlight](https://docs.astro.build/en/guides/markdown-content/#syntax-highlighting) for
+content that is actually hosted somewhere else (e.g. GitHub).
+
+### Usage
+
+```mdx
+import { RemoteCode } from '@fusionauth/astro-components';
+
+<RemoteCode lang="json" url="https://example.com/file.json"/>
+```
+
+This is equivalent of rendering a `<Code lang="json" code="..." />` with the contents of that JSON file.
+
+### Props
+
+- `url` (required): address with the file to download.
+- `lang` (optional): language for the code (default: `plaintext`).
+- `tags` (optional): tags to extract specific lines from the file.
+  See [Lines selection by Tags](#selecting-lines-via-tags).
+
+Any other prop will be forwarded to the underlying `<Code>` component.
+
+### Selecting Lines
+
+This component can retrieve some lines from the remote file according to a custom selection.
+
+#### Selecting Lines via Query String
+
+If you just want to show some specific lines, you can pass an argument to the query string like `#L<start>-L<end>`.
+
+Example:
+
+```mdx
+<RemoteCode lang="javascript" url="https://example.com/file.js#L9-L12"/>
+```
+
+It will only render lines 9, 10, 11, and 12 from the file.
+
+> Tip: this is the same syntax used by GitHub to mark lines in the UI.
+
+#### Selecting Lines via Tags
+
+If you own the remote file to be injected, you can add a few comments to mark which lines you want to show, and then
+pass a `tags="tag-name"` property to the component, which will render lines between `tag::tag-name` and `end::tag-name`.
+
+For instance, if you have the file below:
+
+```javascript
+const express = require('express');
+const app = express();
+
+// tag::listen
+app.listen(3000, () => {
+  console.log('App listening on port 3000');
+});
+// end::listen
+```
+
+To render those lines for the `listen` function and its callback, write your code like this.
+
+```mdx
+<RemoteCode lang="javascript" url="https://example.com/file.js" tags="listen"/>
+```
+
+## `<RemoteValue>`
+
+Instead of hard-coding values from an external file (e.g. some file from the demo app you are writing about), you can
+use the `<RemoteValue>` component to render a specific value from that file.
+
+### Usage
+
+A simple usage example for the component (which will cover most cases) is when you have the following JSON file hosted
+somewhere (e.g. GitHub) and you are writing a doc that mention that user.
+
+```json
+{
+  "user": {
+    "email": "richard.hendricks@example.com",
+    "username": "richard.hendricks",
+    "role": "user"
+  }
+}
+```
+
+Instead of hard-coding the value `richard.hendricks` and taking the risk of your remote file being out-of-sync with your
+document, you can use:
+
+```mdx
+import { RemoteValue } from '@fusionauth/astro-components';
+
+You are going to log in as <RemoteValue url="https://example.com/file.json" selector="$.user.username" />.
+```
+
+This will extract the username from that JSON value and render this instead:
+
+```
+You are going to log in as richard.hendricks.
+```
+
+> Read more about [Selectors](#Selectors).
+
+### Props
+
+* `url` (required): remote URL to fetch the file from
+* `selector` (required): parser-dependent syntax to extract the value from the remote file
+* `parser` (optional): value from the `Parser` enum object exported by the component
+    * If not defined, the component will use the file extension from the URL
+* `defaultValue` (optional): default value if we cannot retrieve the element (otherwise, we'll render "unknown")
+    * This is recommended in case you ever change the remote file and the selector doesn't work anymore.
+
+#### Parsers
+
+Currently, we only support JSON files, but the component is ready to support other extensions in the future (e.g. YAML
+or XML files), so in the future we could have something like this:
+
+```mdx
+import { RemoteValue, RemoteValueParser } from '@fusionauth/astro-components';
+
+<RemoteValue url="https://example.com/file.yaml"
+             parser={Parser.YAML}
+             selector="some.yaml.selector.in.the.future"
+/>
+```
+
+#### Selectors
+
+The `selector` can either be a `string` or a `function`.
+
+##### Selector Strings
+
+When using `string`, you need to check the specific documentation for the parser we use. As we only have JSON right now,
+please check [`jsonpath-plus`](https://www.npmjs.com/package/jsonpath-plus), which implements an XPath-based syntax.
+
+##### Selector Functions
+
+When using `function`, we'll pass the parsed file (e.g. the JSON object) as an argument and the function should return
+the value.
+
+##### Selector Examples
+
+These elements will render the same value:
+
+```mdx
+<RemoteValue url="https://example.com/file.json"
+             selector={(element) => element.users.find(e => e.role === 'user').username}
+/>
+
+<RemoteValue url="https://example.com/file.json"
+             selector="$.users.[?(@.role === 'user')].username"
+/>
+```
+
+### Common rendering scenarios
+
+#### Rendering inside custom components
+
+If you need to render a custom component, you can use [`astro`'s way of passing callback as a child](https://docs.astro.build/en/reference/api-reference/#astroslotsrender):
+
+```mdx
+<RemoteValue
+  url="https://example.com/file.json"
+  selector="$.variables.clientId">
+  {(value) => <Code lang="shell" code={`CLIENT_ID=${value} some-command`}/>}
+</RemoteValue>
+```
+
+This is specially useful when you need to fetch several values and render them all in the same component:
+
+
+```mdx
+<RemoteValue
+  url="https://example.com/file.json"
+  selector="$.variables">
+  {(vars) => <Code lang="shell" code={`CLIENT_ID=${vars.clientId} CLIENT_SECRET=${vars.clientSecret} some-command`}/>}
+</RemoteValue>
+```
+
+#### Rendering inside backticks
+
+Rendering inside inline backticks won't work, but you can use standard `<code>` elements instead.
+
+```mdx
+# This won't work
+`<RemoteValue url="..."/>`
+
+# Use this instead:
+<code><RemoteValue url="..." /></code>
+```
+
+## License
+
+This code is available as open source under the terms of the [Apache v2.0 License](https://opensource.org/licenses/Apache-2.0).