shoelace-rails-ui 0.1.0

data/remote-src/2.0.0.beta64/shoelace-next/docs/frameworks/react.md

@@ -0,0 +1,156 @@
+# React
+
+Shoelace offers a React version of every component to provide an idiomatic experience for React users. You can easily toggle between HTML and React examples throughout the documentation.
+
+## Installation
+
+To add Shoelace to your React app, install the package from npm.
+
+```bash
+npm install @shoelace-style/shoelace
+```
+
+Next, [include a theme](/getting-started/themes) and set the [base path](/getting-started/installation#setting-the-base-path) for icons and other assets. In this example, we'll import the light theme and use the CDN as a base path.
+
+```jsx
+// App.jsx
+import '@shoelace-style/shoelace/dist/themes/light.css';
+import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path';
+
+setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/');
+```
+
+?> If you'd rather not use the CDN for assets, you can create a [build task](https://webpack.js.org/plugins/copy-webpack-plugin/) that copies `node_modules/@shoelace-style/shoelace/dist/assets` into your app's `public` directory. Then you can point the base path to that folder instead.
+
+Now you can start using components!
+
+## Usage
+
+### Importing Components
+
+Every Shoelace component is available to import as a React component. Note that we're importing the `<SlButton>` _React component_ instead of the `<sl-button>` _custom element_ in the example below.
+
+```jsx
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
+
+const MyComponent = () => (
+  <SlButton variant="primary">
+    Click me
+  </SlButton>
+);
+
+export default MyComponent;
+```
+
+You can find a copy + paste import for each component in the "importing" section of its documentation.
+
+### Event Handling
+
+Many Shoelace components emit [custom events](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent). For example, the [input component](/components/input) emits the `sl-input` event when it receives input. In React, you can listen for the event using `onSlInput`.
+
+Here's how you can bind the input's value to a state variable.
+
+```jsx
+import { useState } from 'react';
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
+
+function MyComponent() {
+  const [value, setValue] = useState('');
+
+  return (
+    <SlInput 
+      value={value} 
+      onSlInput={event => setValue(event.target.value)} 
+    />
+  )
+};
+
+export default MyComponent;
+```
+
+If you're using TypeScript, it's important to note that `event.target` will be a reference to the underlying custom element. You can use `(event.target as any).value` as a quick fix, or you can strongly type the event target as shown below.
+
+```tsx
+import { useState } from 'react';
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
+import type SlInputElement from '@shoelace-style/shoelace/dist/components/input/input';
+
+function MyComponent() {
+  const [value, setValue] = useState('');
+
+  return (
+    <SlInput 
+      value={value} 
+      onSlInput={event => setValue((event.target as SlInputElement).value)} 
+    />
+  )
+};
+
+export default MyComponent;
+```
+
+## Testing with Jest
+
+Testing with web components can be challenging if your test environment runs in a Node environment (i.e. it doesn't run in a real browser). Fortunately, [Jest](https://jestjs.io/) has made a number of strides to support web components and provide additional browser APIs. However, it's still not a complete replication of a browser environment.
+
+Here are some tips that will help smooth things over if you're having trouble with Jest + Shoelace.
+
+?> If you're looking for a fast, modern testing alternative, consider [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/).
+
+### Upgrade Jest
+
+Jest underwent a major revamp and received support for web components in [version 26.5.0](https://github.com/facebook/jest/blob/main/CHANGELOG.md#2650) when it introduced [JSDOM 16.2.0](https://github.com/jsdom/jsdom/blob/master/Changelog.md#1620). This release also included a number of mocks for built-in browser functions such as `MutationObserver`, `document.createRange`, and others.
+
+If you're using [Create React App](https://reactjs.org/docs/create-a-new-react-app.html#create-react-app), you can update `react-scripts` which will also update Jest.
+
+```
+npm install react-scripts@latest
+```
+
+### Mock Missing APIs
+
+Some components use `window.matchMedia`, but this function isn't supported by JSDOM so you'll need to mock it yourself.
+
+In `src/setupTests.js`, add the following.
+
+```js
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: jest.fn().mockImplementation(query => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: jest.fn(), // deprecated
+    removeListener: jest.fn(), // deprecated
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+    dispatchEvent: jest.fn(),
+  })),
+});
+```
+
+For more details, refer to Jest's [manual mocking](https://jestjs.io/docs/manual-mocks#mocking-methods-which-are-not-implemented-in-jsdom) documentation.
+
+### Transform ES Modules
+
+ES Modules are a [well-supported browser standard](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/). This is how Shoelace is distributed, but most React apps expect CommonJS. As a result, you'll probably run into the following error.
+
+```
+Error: Unable to import outside of a module
+```
+
+To fix this, add the following to your `package.json` which tells the transpiler to process Shoelace modules.
+
+```js
+{
+  "jest": {
+    "transformIgnorePatterns": ["node_modules/?!(@shoelace)"]
+  }
+}
+```
+
+These instructions are for apps created via Create React App. If you're using Jest directly, you can add `transformIgnorePatterns` directly into `jest.config.js`.
+
+For more details, refer to Jest's [`transformIgnorePatterns` customization](https://jestjs.io/docs/tutorial-react-native#transformignorepatterns-customization) documentation.
+
+?> Are you using Shoelace with React? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/react.md)

data/remote-src/2.0.0.beta64/shoelace-next/docs/frameworks/vue.md

@@ -0,0 +1,92 @@
+# Vue
+
+Vue [plays nice](https://custom-elements-everywhere.com/#vue) with custom elements, so you can use Shoelace in your Vue apps with ease.
+
+?> These instructions are for Vue 2. If you're using Vue 3, [please help us update this page](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue.md).
+
+## Installation
+
+To add Shoelace to your Vue app, install the package from npm.
+
+```bash
+npm install @shoelace-style/shoelace
+```
+
+Next, [include a theme](/getting-started/themes) and set the [base path](/getting-started/installation#setting-the-base-path) for icons and other assets. In this example, we'll import the light theme and use the CDN as a base path.
+
+```jsx
+import '@shoelace-style/shoelace/dist/themes/light.css';
+import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path';
+
+setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/');
+```
+
+?> If you'd rather not use the CDN for assets, you can create a build task that copies `node_modules/@shoelace-style/shoelace/dist/assets` into a public folder in your app. Then you can point the base path to that folder instead.
+
+## Configuration
+
+You'll need to tell Vue to ignore Shoelace components. This is pretty easy because they all start with `sl-`.
+
+```js
+import { createApp } from 'vue';
+import App from './App.vue';
+
+const app = createApp(App);
+
+app.config.compilerOptions.isCustomElement = tag => tag.startsWith('sl-');
+
+app.mount('#app');
+```
+
+Now you can start using Shoelace components in your app!
+
+## Usage
+
+### Binding Complex Data
+
+When binding complex data such as objects and arrays, use the `.prop` modifier to make Vue bind them as a property instead of an attribute.
+
+```html
+<sl-color-picker :swatches.prop="mySwatches" />
+```
+
+### Two-way Binding
+
+One caveat is there's currently [no support for v-model on custom elements](https://github.com/vuejs/vue/issues/7830), but you can still achieve two-way binding manually.
+
+```html
+<!-- This doesn't work -->
+<sl-input v-model="name">
+
+<!-- This works, but it's a bit longer -->
+<sl-input :value="name" @input="name = $event.target.value">
+```
+
+If that's too verbose for your liking, you can use a custom directive instead. [This utility](https://www.npmjs.com/package/@shoelace-style/vue-sl-model) adds a custom directive that will work just like `v-model` but for Shoelace components. To install it, use this command.
+
+```bash
+npm install @shoelace-style/vue-sl-model
+```
+
+Next, import the directive and enable it like this.
+
+```js
+import ShoelaceModelDirective from '@shoelace-style/vue-sl-model';
+import { createApp } from 'vue';
+import App from './App.vue';
+
+const app = createApp(App);
+app.use(ShoelaceModelDirective);
+
+app.config.compilerOptions.isCustomElement = tag => tag.startsWith('sl-');
+
+app.mount('#app');
+```
+
+Now you can use the `v-sl-model` directive to keep your data in sync!
+
+```html
+<sl-input v-sl-model="name">
+```
+
+?> Are you using Shoelace with Vue? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue.md)

data/remote-src/2.0.0.beta64/shoelace-next/docs/getting-started/customizing.md

@@ -0,0 +1,153 @@
+# Customizing
+
+Shoelace components can be customized at a high level through design tokens. This gives you control over theme colors and general styling. For more advanced customizations, you can make use of component parts and custom properties to target individual components.
+
+## Design Tokens
+
+Shoelace makes use of several design tokens to provide a consistent appearance across components. You can customize them and use them in your own application with pure CSS — no preprocessor required.
+
+Design tokens offer a high-level way to customize the library with minimal effort. There are no component-specific variables, however, as design tokens are intended to be generic and highly reusable. To customize an individual component, refer to the section entitled [Component Parts](#component-parts).
+
+Design tokens are accessed through CSS custom properties that are defined in your theme. Because design tokens live at the page level, they're prefixed with `--sl-` to avoid collisions with other libraries.
+
+To customize a design token, simply override it in your stylesheet using a `:root` block. Here's an example that changes the primary theme to purple based on existing [color primitives](/tokens/color#primitives).
+
+```css
+:root {
+  /* Changes the primary theme color to purple using primitives */
+  --sl-color-primary-50: var(--sl-color-purple-50);
+  --sl-color-primary-100: var(--sl-color-purple-100);
+  --sl-color-primary-200: var(--sl-color-purple-200);
+  --sl-color-primary-300: var(--sl-color-purple-300);
+  --sl-color-primary-400: var(--sl-color-purple-400);
+  --sl-color-primary-500: var(--sl-color-purple-500);
+  --sl-color-primary-600: var(--sl-color-purple-600);
+  --sl-color-primary-700: var(--sl-color-purple-700);
+  --sl-color-primary-800: var(--sl-color-purple-800);
+  --sl-color-primary-900: var(--sl-color-purple-900);
+  --sl-color-primary-950: var(--sl-color-purple-950);
+}
+```
+
+Many design tokens are described further along in this documentation. For a complete list, refer to `src/themes/light.styles.ts` in the project's [source code](https://github.com/shoelace-style/shoelace/blob/current/src/themes/light.styles.ts).
+
+## Component Parts
+
+Whereas design tokens offer a high-level way to customize the library, component parts offer a low-level way to customize individual components. Again, this is done with pure CSS — no preprocessor required.
+
+Shoelace components use a [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to encapsulate their styles and behaviors. As a result, you can't simply target their internals with the usual CSS selectors. Instead, components expose "parts" that can be targeted with the [CSS part selector](https://developer.mozilla.org/en-US/docs/Web/CSS/::part), or `::part()`.
+
+Here's an example that modifies buttons with the `tomato-button` class.
+
+```html preview
+<sl-button class="tomato-button"> Tomato Button </sl-button>
+
+<style>
+  .tomato-button::part(base) {
+    background: var(--sl-color-neutral-0);
+    border: solid 1px tomato;
+  }
+
+  .tomato-button::part(base):hover {
+    background: rgba(255, 99, 71, 0.1);
+  }
+
+  .tomato-button::part(base):active {
+    background: rgba(255, 99, 71, 0.2);
+  }
+
+  .tomato-button::part(base):focus-visible {
+    box-shadow: 0 0 0 3px rgba(255, 99, 71, 0.33);
+  }
+
+  .tomato-button::part(label) {
+    color: tomato;
+  }
+</style>
+```
+
+At first glance, this approach might seem a bit verbose or even limiting, but it comes with a few important advantages:
+
+- Customizations can be made to components with explicit selectors, such as `::part(icon)`, rather than implicit selectors, such as `.button > div > span + .icon`, that are much more fragile.
+
+- The internal structure of a component will likely change as it evolves. By exposing component parts through an API, the internals can be reworked without fear of breaking customizations as long as its parts remain intact.
+
+- It encourages us to think more about how components are designed and how customizations should be allowed before users can take advantage of them. Once we opt a part into the component's API, it's guaranteed to be supported and can't be removed until a major version of the library is released.
+
+Most (but not all) components expose parts. You can find them in each component's API documentation under the "CSS Parts" section.
+
+## Custom Properties
+
+For convenience, some components expose CSS custom properties you can override. These are not design tokens, nor do they have the same `--sl-` prefix since they're scoped to a component.
+
+You can set custom properties on a component in your stylesheet.
+
+```css
+sl-avatar {
+  --size: 6rem;
+}
+```
+
+This will also work if you need to target a subset of components with a specific class.
+
+```css
+sl-avatar.your-class {
+  --size: 6rem;
+}
+```
+
+Alternatively, you can set them inline directly on the element.
+
+```html
+<sl-avatar style="--size: 6rem;"></sl-avatar>
+```
+
+Not all components expose CSS custom properties. For those that do, they can be found in the component's API documentation.
+
+## Animations
+
+Some components use animation, such as when a dialog is shown or hidden. Animations are performed using the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) rather than CSS. However, you can still customize them through Shoelace's animation registry. If a component has customizable animations, they'll be listed in the "Animation" section of its documentation.
+
+To customize a default animation, use the `setDefaultAnimation()` method. The function accepts an animation name (found in the component's docs) and an object with `keyframes` and `options` or `null` to disable the animation.
+
+This example will make all dialogs use a custom show animation.
+
+```js
+import { setDefaultAnimation } from '@shoelace-style/shoelace/dist/utilities/animation-registry.js';
+
+// Change the default animation for all dialogs
+setDefaultAnimation('dialog.show', {
+  keyframes: [
+    { transform: 'rotate(-10deg) scale(0.5)', opacity: '0' },
+    { transform: 'rotate(0deg) scale(1)', opacity: '1' }
+  ],
+  options: {
+    duration: 500
+  }
+});
+```
+
+If you only want to target a single component, use the `setAnimation()` method instead. This function accepts an element, an animation name, and an object comprised of animation `keyframes` and `options`.
+
+In this example, only the target dialog will use a custom show animation.
+
+```js
+import { setAnimation } from '@shoelace-style/shoelace/dist/utilities/animation-registry.js';
+
+// Change the animation for a single dialog
+const dialog = document.querySelector('#my-dialog');
+
+setAnimation(dialog, 'dialog.show', {
+  keyframes: [
+    { transform: 'rotate(-10deg) scale(0.5)', opacity: '0' },
+    { transform: 'rotate(0deg) scale(1)', opacity: '1' }
+  ],
+  options: {
+    duration: 500
+  }
+});
+```
+
+To learn more about creating Web Animations, refer to the documentation for [`Element.animate()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animate).
+
+?> Animations respect the users `prefers-reduced-motion` setting. When this setting is enabled, animations will not be played. To disable animations for all users, pass in `null` instead of a keyframes/options object.