shoelace-rails-ui 0.1.0

data/remote-src/2.0.0.beta64/shoelace-next/docs/tutorials/integrating-with-laravel.md

@@ -0,0 +1,117 @@
+# Integrating with Laravel
+
+This page explains how to integrate Shoelace with a [Laravel](https://laravel.com) app using a local Webpack bundle.
+
+?> This is a community-maintained document. Please [ask the community](/resources/community) if you have questions about this integration. You can also [suggest improvements](https://github.com/shoelace-style/shoelace/blob/next/docs/tutorials/integrating-with-laravel.md) to make it better.
+
+## Requirements
+
+This integration has been tested with the following:
+
+- Laravel >= 8
+- Node >= 14
+- Laravel Mix >= 6
+
+## Instructions
+
+These instructions assume an out of the box [Laravel 8+ install](https://laravel.com/docs/8.x/installation) that uses [Laravel Mix](https://laravel.com/docs/8.x/mix) to compile assets.
+Be sure to run `npm install` to install the default Laravel front-end dependencies before installing Shoelace.
+
+### Install the Shoelace package
+
+```bash
+npm install @shoelace-style/shoelace
+```
+
+### Import the Default Theme
+
+Import Shoelace's default theme (stylesheet) in `/resources/css/app.css`:
+
+```css
+@import '/node_modules/@shoelace-style/shoelace/dist/themes/light.css';
+```
+
+### Import Your Shoelace Components
+
+Import each Shoelace component you plan to use in `/resources/js/bootstrap.js`. Since [Laravel Mix](https://laravel.com/docs/8.x/mix) uses Webpack, use the full path to each component -- as outlined in the [Cherry Picking instructions](https://shoelace.style/getting-started/installation?id=cherry-picking). You can find the full import statement for a component in the _Importing_ section of the component's documentation (use the _Bundler_ import). Your imports should look similar to:
+
+```js
+import '@shoelace-style/shoelace/dist/components/button/button.js';
+import '@shoelace-style/shoelace/dist/components/dialog/dialog.js';
+import '@shoelace-style/shoelace/dist/components/drawer/drawer.js';
+import '@shoelace-style/shoelace/dist/components/menu/menu.js';
+import '@shoelace-style/shoelace/dist/components/menu-item/menu-item.js';
+```
+
+### Set the Base Path
+
+Add the base path to your Shoelace assets (icons, images, etc.) in `/resources/js/bootstrap.js`. The path must point to the same folder where you copy assets to in the next step.
+
+```js
+import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path.js';
+setBasePath('/');
+```
+
+Here's an example `/resources/js/bootstrap.js` file, after importing and setting the base path and components.
+
+```js
+import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path.js';
+setBasePath('/assets');
+
+import '@shoelace-style/shoelace/dist/components/button/button.js';
+import '@shoelace-style/shoelace/dist/components/dialog/dialog.js';
+import '@shoelace-style/shoelace/dist/components/drawer/drawer.js';
+import '@shoelace-style/shoelace/dist/components/menu/menu.js';
+import '@shoelace-style/shoelace/dist/components/menu-item/menu-item.js';
+```
+
+### Configure Laravel Mix
+
+[Laravel Mix](https://laravel.com/docs/8.x/mix) is a wrapper around Webpack that simplifies configuration. Mix is used by default for compiling front-end assets in Laravel.
+
+Modify `webpack.mix.js` to add Shoelace's assets to Webpack's build process:
+
+```js
+mix
+  .js('resources/js/app.js', 'public/js')
+  .postCss('resources/css/app.css', 'public/css', [])
+  .copy('node_modules/@shoelace-style/shoelace/dist/assets', 'public/assets');
+```
+
+Consider [extracting vendor libraries](https://laravel.com/docs/8.x/mix#vendor-extraction) to a separate file. This splits frequently updated vendor libraries (like Shoelace) from your front-end application code -- for better long-term caching.
+Here's an example `webpack.mix.js` file that compiles and splits your JS into `app.js` and `vendor.js` files, and builds an optimized CSS bundle using PostCSS.
+
+```js
+mix
+  .js('resources/js/app.js', 'public/js')
+  .postCss('resources/css/app.css', 'public/css', [])
+  .copy('node_modules/@shoelace-style/shoelace/dist/assets', 'public/assets')
+  .extract(); // extracts libraries in node_modules to vendor.js
+```
+
+### Compile Front-End Assets
+
+Run the [Laravel Mix](https://laravel.com/docs/8.x/mix) npm scripts to build your application's CSS and JavaScript code.
+
+```bash
+## build a development bundle
+npm run dev
+
+## build a production bundle
+npm run prod
+```
+
+### Include Front-End Assets in Your Layout File
+
+Most full-stack Laravel applications use [layouts](https://laravel.com/docs/8.x/blade#building-layouts) to define the basic structure of a page.
+After compiling your front-end assets (above), include them in your top-level layouts/templates. The following example uses the [Laravel asset helper](https://laravel.com/docs/8.x/helpers#method-asset) to generate a full URL.
+
+```html
+<script defer src="{{ asset('js/manifest.js') }}"></script>
+<script defer src="{{ asset('js/vendor.js') }}"></script>
+<script defer src="{{ asset('/js/app.js') }}"></script>
+
+<link href="{{ asset('css/app.css') }}" rel="stylesheet" />
+```
+
+Have fun using Shoelace components in your Laravel app!

data/remote-src/2.0.0.beta64/shoelace-next/docs/tutorials/integrating-with-nextjs.md

@@ -0,0 +1,137 @@
+# Integrating with NextJS
+
+This page explains how to integrate Shoelace with a NextJS app.
+
+?> This is a community-maintained document. Please [ask the community](/resources/community) if you have questions about this integration. You can also [suggest improvements](https://github.com/shoelace-style/shoelace/blob/next/docs/tutorials/integrating-with-nextjs.md) to make it better.
+
+## Requirements
+
+This integration has been tested with the following:
+
+- Node >= 12.10
+- NextJS >= 10.0.5
+
+## Instructions
+
+To get started using Shoelace with NextJS, the following packages must be installed.
+
+```bash
+yarn add @shoelace-style/shoelace @shoelace-style/shoelace copy-webpack-plugin next-compose-plugins next-transpile-modules
+```
+
+### Importing the Default Theme
+
+The next step is to import Shoelace's default theme (stylesheet) in your `_app.js` file:
+
+```css
+import '@shoelace-style/shoelace/dist/themes/light.css';
+```
+
+### Defining Custom Elements
+
+After importing the theme, you'll need to import the JavaScript files for Shoelace. However, this is a bit tricky to do in NextJS thanks to the SSR environment not having any of the required browser APIs to define endpoints.
+
+We'll want to create a component that uses [React's `useLayoutEffect`](https://reactjs.org/docs/hooks-reference.html#uselayouteffect) to add in the custom components before the first render:
+
+```javascript
+function CustomEls({ URL }) {
+  // useRef to avoid re-renders
+  const customEls = useRef(false);
+
+  useLayoutEffect(() => {
+    if (customEls.current) {
+      return;
+    }
+
+    const { setBasePath } = require('@shoelace-style/shoelace/dist/utilities/base-path');
+
+    setBasePath(`${URL}/static/static`);
+
+    // This imports all components
+    require('@shoelace-style/shoelace/dist/shoelace');
+
+    // If you want to selectively import components, replace this line with your own definitions
+    // require('@shoelace-style/shoelace/dist/components/button/button');
+
+    customEls.current = true;
+  }, [URL, customEls]);
+
+  return null;
+}
+```
+
+?> If we use `useEffect` instead of `useLayoutEffect`, the initial render will occur with the expected `sl-` props applied, but the subsequent render (caused by the `useEffect`) will remove those props as the custom components initialize. We _must_ use `useLayoutEffect` to have expected behavior
+
+?> This will import all Shoelace components for convenience. To selectively import components, refer to the [Using webpack](/getting-started/installation?id=using-webpack) section of the docs.
+
+You may be wondering where the `URL` property is coming from. We'll address that in the next few sections.
+
+### Using Our New Component In Code
+
+While we need to use `useLayoutEffect` for the initial render, NextJS will throw a warning at us for trying to use `useLayoutEffect` in SSR, which is disallowed. To fix this problem, we'll conditionally render the `CustomEls` component to only render in the browser
+
+```javascript
+function MyApp({ Component, pageProps, URL }) {
+  return (
+    <>
+      {process.browser && <CustomEls URL={URL} />}
+      <Component {...pageProps} />
+    </>
+  );
+}
+```
+
+### Environmental Variable
+
+However, to make `setBasePath()` work as-expected, we need to know where the file is hosted. To do this, we need to set [environmental variables](https://nextjs.org/docs/basic-features/environment-variables). Create a `.local.env` file and put the following inside:
+
+```
+BASE_URL="localhost:3000"
+```
+
+Then, modify your `MyApp` class in `_app.js` to pass this process environment into your render:
+
+```javascript
+MyApp.getInitialProps = async context => {
+  const URL = process.env.BASE_URL;
+
+  return {
+    URL
+  };
+};
+```
+
+?> You'll need to set this `BASE_URL` variable inside the build process of whatever local build or CI/CD you have. This will need to be an absolute URL, as a relative URL will cause shoelace to throw a warning
+
+### webpack Config
+
+Next we need to add Shoelace's assets to the final build output. To do this, modify `next.config.js` to look like this.
+
+```javascript
+const path = require('path');
+const CopyPlugin = require('copy-webpack-plugin');
+const withPlugins = require('next-compose-plugins');
+const withTM = require('next-transpile-modules')(['@shoelace-style/shoelace']);
+
+module.exports = withPlugins([withTM], {
+  webpack: config => {
+    config.plugins.push(
+      new CopyPlugin({
+        patterns: [
+          {
+            from: path.resolve(__dirname, 'node_modules/@shoelace-style/shoelace/dist/assets/icons'),
+            to: path.resolve(__dirname, 'static/icons')
+          }
+        ]
+      })
+    );
+    return config;
+  }
+});
+```
+
+?> This will copy the files from `node_modules` into your `static` folder on every development serve or build. You may want to avoid committing these into your repo. To do so, simply add `static/assets` into your `.gitignore` folder
+
+## Additional Resources
+
+- There is a third-party [example repo](https://github.com/crutchcorn/nextjs-shoelace-example), courtesy of [crutchcorn](https://github.com/crutchcorn), available to help you get started.

data/remote-src/2.0.0.beta64/shoelace-next/docs/tutorials/integrating-with-rails.md

@@ -0,0 +1,103 @@
+# Integrating with Rails
+
+This page explains how to integrate Shoelace with a Rails app.
+
+?> This is a community-maintained document. Please [ask the community](/resources/community) if you have questions about this integration. You can also [suggest improvements](https://github.com/shoelace-style/shoelace/blob/next/docs/tutorials/integrating-with-rails.md) to make it better.
+
+## Requirements
+
+This integration has been tested with the following:
+
+- Rails >= 6
+- Node >= 12.10
+- Webpacker >= 5
+
+## Instructions
+
+To get started using Shoelace with Rails, the following packages must be installed.
+
+```bash
+yarn add @shoelace-style/shoelace copy-webpack-plugin
+```
+
+### Importing the Default Theme
+
+The next step is to import Shoelace's default theme (stylesheet) in `app/javascript/stylesheets/application.scss`.
+
+```css
+@import '~@shoelace-style/shoelace/dist/themes/light';
+@import '~@shoelace-style/shoelace/dist/themes/dark'; // Optional dark theme
+```
+
+Fore more details about themes, please refer to [Theme Basics](/getting-started/themes?id=theme-basics).
+
+### Importing Required Scripts
+
+After importing the theme, you'll need to import the JavaScript files for Shoelace. Add the following code to `app/javascript/packs/application.js`.
+
+```js
+import '../stylesheets/application.scss'
+import { setBasePath, SlAlert, SlAnimation, SlButton, ... } from '@shoelace-style/shoelace'
+
+// ...
+
+const rootUrl = document.currentScript.src.replace(/\/packs.*$/, '')
+
+// Path to the assets folder (should be independent from the current script source path
+// to work correctly in different environments)
+setBasePath(rootUrl + '/packs/js/')
+```
+
+### webpack Config
+
+Next we need to add Shoelace's assets to the final build output. To do this, modify `config/webpack/environment.js` to look like this.
+
+```js
+const { environment } = require('@rails/webpacker')
+
+// Shoelace config
+const path = require('path')
+const CopyPlugin = require('copy-webpack-plugin')
+
+// Add shoelace assets to webpack's build process
+environment.plugins.append(
+  'CopyPlugin',
+  new CopyPlugin({
+    patterns: [
+      {
+        from: path.resolve(
+          __dirname,
+          '../../node_modules/@shoelace-style/shoelace/dist/assets'
+        ),
+        to: path.resolve(__dirname, '../../public/packs/js/assets')
+      }
+    ]
+  })
+)
+
+module.exports = environment
+```
+
+### Adding Pack Tags
+
+The final step is to add the corresponding `pack_tags` to the page. You should have the following `tags` in the `<head>` section of `app/views/layouts/application.html.erb`.
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <!-- ... -->
+
+    <%= stylesheet_pack_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
+    <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
+  </head>
+  <body><%= yield %></body>
+</html>
+```
+
+Now you can start using Shoelace components with Rails!
+
+## Additional Resources
+
+- There is a third-party [example repo](https://github.com/ParamagicDev/rails-shoelace-example), courtesy of [ParamagicDev](https://github.com/ParamagicDev) available to help you get started.
+- If you would like to avoid repeating this process, check out the associated [Railsbyte for Shoelace](https://railsbytes.com/templates/X8BsEb).

data/remote-src/2.0.0.beta64/shoelace-next/lint-staged.config.js

@@ -0,0 +1,4 @@
+export default {
+  '*.{js,ts,jsx,tsx,json,html,xml,css,scss,sass,md}': 'cspell --no-must-find-files',
+  '*': 'prettier --write --ignore-unknown'
+};