shoelace-rails-ui 0.1.0

data/remote-src/2.0.0.beta64/shoelace-next/docs/components/dropdown.md

@@ -0,0 +1,389 @@
+# Dropdown
+
+[component-header:sl-dropdown]
+
+Dropdowns expose additional content that "drops down" in a panel.
+
+Dropdowns consist of a trigger and a panel. By default, activating the trigger will expose the panel and interacting outside of the panel will close it.
+
+Dropdowns are designed to work well with [menus](/components/menu) to provide a list of options the user can select from. However, dropdowns can also be used in lower-level applications (e.g. [color picker](/components/color-picker) and [select](/components/select)). The API gives you complete control over showing, hiding, and positioning the panel.
+
+```html preview
+<sl-dropdown>
+  <sl-button slot="trigger" caret>Dropdown</sl-button>
+  <sl-menu>
+    <sl-menu-item>Dropdown Item 1</sl-menu-item>
+    <sl-menu-item>Dropdown Item 2</sl-menu-item>
+    <sl-menu-item>Dropdown Item 3</sl-menu-item>
+    <sl-divider></sl-divider>
+    <sl-menu-item checked>Checked</sl-menu-item>
+    <sl-menu-item disabled>Disabled</sl-menu-item>
+    <sl-divider></sl-divider>
+    <sl-menu-item>
+      Prefix
+      <sl-icon slot="prefix" name="gift"></sl-icon>
+    </sl-menu-item>
+    <sl-menu-item>
+      Suffix Icon
+      <sl-icon slot="suffix" name="heart"></sl-icon>
+    </sl-menu-item>
+  </sl-menu>
+</sl-dropdown>
+```
+
+```jsx react
+import { 
+  SlButton,
+  SlDivider,
+  SlDropdown,
+  SlIcon,
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlDropdown>
+    <SlButton slot="trigger" caret>Dropdown</SlButton>
+    <SlMenu>
+      <SlMenuItem>Dropdown Item 1</SlMenuItem>
+      <SlMenuItem>Dropdown Item 2</SlMenuItem>
+      <SlMenuItem>Dropdown Item 3</SlMenuItem>
+      <SlDivider />
+      <SlMenuItem checked>Checked</SlMenuItem>
+      <SlMenuItem disabled>Disabled</SlMenuItem>
+      <SlDivider />
+      <SlMenuItem>
+        Prefix
+        <SlIcon slot="prefix" name="gift" />
+      </SlMenuItem>
+      <SlMenuItem>
+        Suffix Icon
+        <SlIcon slot="suffix" name="heart" />
+      </SlMenuItem>
+    </SlMenu>
+  </SlDropdown>  
+);
+```
+
+## Examples
+
+### Getting the Selected Item
+
+When dropdowns are used with [menus](/components/menu), you can listen for the `sl-select` event to determine which menu item was selected. The menu item element will be exposed in `event.detail.item`. You can set `value` props to make it easier to identify commands.
+
+```html preview
+<div class="dropdown-selection">
+  <sl-dropdown>
+    <sl-button slot="trigger" caret>Edit</sl-button>
+    <sl-menu>
+      <sl-menu-item value="cut">Cut</sl-menu-item>
+      <sl-menu-item value="copy">Copy</sl-menu-item>
+      <sl-menu-item value="paste">Paste</sl-menu-item>
+    </sl-menu>
+  </sl-dropdown>
+</div>
+
+<script>
+  const container = document.querySelector('.dropdown-selection');
+  const dropdown = container.querySelector('sl-dropdown');
+
+  dropdown.addEventListener('sl-select', event => {
+    const selectedItem = event.detail.item;
+    console.log(selectedItem.value);
+  });
+</script>
+```
+
+```jsx react
+import { 
+  SlButton,
+  SlDropdown,
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  function handleSelect(event) {
+    const selectedItem = event.detail.item;
+    console.log(selectedItem.value);
+  }
+
+  return (
+    <SlDropdown>
+      <SlButton slot="trigger" caret>Edit</SlButton>
+      <SlMenu onSlSelect={handleSelect}>
+        <SlMenuItem value="cut">Cut</SlMenuItem>
+        <SlMenuItem value="copy">Copy</SlMenuItem>
+        <SlMenuItem value="paste">Paste</SlMenuItem>
+      </SlMenu>
+    </SlDropdown> 
+  );
+};
+```
+
+Alternatively, you can listen for the `click` event on individual menu items. Note that, using this approach, disabled menu items will still emit a `click` event.
+
+```html preview
+<div class="dropdown-selection-alt">
+  <sl-dropdown>
+    <sl-button slot="trigger" caret>Edit</sl-button>
+    <sl-menu>
+      <sl-menu-item value="cut">Cut</sl-menu-item>
+      <sl-menu-item value="copy">Copy</sl-menu-item>
+      <sl-menu-item value="paste">Paste</sl-menu-item>
+    </sl-menu>
+  </sl-dropdown>
+</div>
+
+<script>
+  const container = document.querySelector('.dropdown-selection-alt');
+  const cut = container.querySelector('sl-menu-item[value="cut"]');
+  const copy = container.querySelector('sl-menu-item[value="copy"]');
+  const paste = container.querySelector('sl-menu-item[value="paste"]');
+
+  cut.addEventListener('click', () => console.log('cut'));
+  copy.addEventListener('click', () => console.log('copy'));
+  paste.addEventListener('click', () => console.log('paste'));
+</script>
+```
+
+```jsx react
+import { 
+  SlButton,
+  SlDropdown,
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  function handleCut() {
+    console.log('cut');
+  }
+
+  function handleCopy() {
+    console.log('copy');
+  }
+
+  function handlePaste() {
+    console.log('paste');
+  }
+
+  return (
+    <SlDropdown>
+      <SlButton slot="trigger" caret>Edit</SlButton>
+      <SlMenu>
+        <SlMenuItem onClick={handleCut}>Cut</SlMenuItem>
+        <SlMenuItem onClick={handleCopy}>Copy</SlMenuItem>
+        <SlMenuItem onClick={handlePaste}>Paste</SlMenuItem>
+      </SlMenu>
+    </SlDropdown> 
+  );
+};
+```
+
+### Placement
+
+The preferred placement of the dropdown can be set with the `placement` attribute. Note that the actual position may vary to ensure the panel remains in the viewport.
+
+```html preview
+<sl-dropdown placement="top-start">
+  <sl-button slot="trigger" caret>Edit</sl-button>
+  <sl-menu>
+    <sl-menu-item>Cut</sl-menu-item>
+    <sl-menu-item>Copy</sl-menu-item>
+    <sl-menu-item>Paste</sl-menu-item>
+    <sl-divider></sl-divider>
+    <sl-menu-item>Find</sl-menu-item>
+    <sl-menu-item>Replace</sl-menu-item>
+  </sl-menu>
+</sl-dropdown>
+```
+
+```jsx react
+import { 
+  SlButton,
+  SlDivider,
+  SlDropdown,
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlDropdown placement="top-start">
+    <SlButton slot="trigger" caret>Edit</SlButton>
+    <SlMenu>
+      <SlMenuItem>Cut</SlMenuItem>
+      <SlMenuItem>Copy</SlMenuItem>
+      <SlMenuItem>Paste</SlMenuItem>
+      <SlDivider />
+      <SlMenuItem>Find</SlMenuItem>
+      <SlMenuItem>Replace</SlMenuItem>
+    </SlMenu>
+  </SlDropdown> 
+);
+```
+
+### Distance
+
+The distance from the panel to the trigger can be customized using the `distance` attribute. This value is specified in pixels.
+
+```html preview
+<sl-dropdown distance="30">
+  <sl-button slot="trigger" caret>Edit</sl-button>
+  <sl-menu>
+    <sl-menu-item>Cut</sl-menu-item>
+    <sl-menu-item>Copy</sl-menu-item>
+    <sl-menu-item>Paste</sl-menu-item>
+    <sl-divider></sl-divider>
+    <sl-menu-item>Find</sl-menu-item>
+    <sl-menu-item>Replace</sl-menu-item>
+  </sl-menu>
+</sl-dropdown>
+```
+
+```jsx react
+import { 
+  SlButton,
+  SlDivider,
+  SlDropdown,
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlDropdown distance={30}>
+    <SlButton slot="trigger" caret>Edit</SlButton>
+    <SlMenu>
+      <SlMenuItem>Cut</SlMenuItem>
+      <SlMenuItem>Copy</SlMenuItem>
+      <SlMenuItem>Paste</SlMenuItem>
+      <SlDivider />
+      <SlMenuItem>Find</SlMenuItem>
+      <SlMenuItem>Replace</SlMenuItem>
+    </SlMenu>
+  </SlDropdown> 
+);
+```
+
+### Skidding
+
+The offset of the panel along the trigger can be customized using the `skidding` attribute. This value is specified in pixels.
+
+```html preview
+<sl-dropdown skidding="30">
+  <sl-button slot="trigger" caret>Edit</sl-button>
+  <sl-menu>
+    <sl-menu-item>Cut</sl-menu-item>
+    <sl-menu-item>Copy</sl-menu-item>
+    <sl-menu-item>Paste</sl-menu-item>
+    <sl-divider></sl-divider>
+    <sl-menu-item>Find</sl-menu-item>
+    <sl-menu-item>Replace</sl-menu-item>
+  </sl-menu>
+</sl-dropdown>
+```
+
+```jsx react
+import { 
+  SlButton,
+  SlDivider,
+  SlDropdown,
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlDropdown skidding={30}>
+    <SlButton slot="trigger" caret>Edit</SlButton>
+    <SlMenu>
+      <SlMenuItem>Cut</SlMenuItem>
+      <SlMenuItem>Copy</SlMenuItem>
+      <SlMenuItem>Paste</SlMenuItem>
+      <SlDivider />
+      <SlMenuItem>Find</SlMenuItem>
+      <SlMenuItem>Replace</SlMenuItem>
+    </SlMenu>
+  </SlDropdown> 
+);
+```
+
+### Hoisting
+
+Dropdown panels will be clipped if they're inside a container that has `overflow: auto|hidden`. The `hoist` attribute forces the panel to use a fixed positioning strategy, allowing it to break out of the container. In this case, the panel will be positioned relative to its containing block, which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
+
+```html preview
+<div class="dropdown-hoist">
+  <sl-dropdown>
+    <sl-button slot="trigger" caret>No Hoist</sl-button>
+    <sl-menu>
+      <sl-menu-item>Item 1</sl-menu-item>
+      <sl-menu-item>Item 2</sl-menu-item>
+      <sl-menu-item>Item 3</sl-menu-item>
+    </sl-menu>
+  </sl-dropdown>
+
+  <sl-dropdown hoist>
+    <sl-button slot="trigger" caret>Hoist</sl-button>
+    <sl-menu>
+      <sl-menu-item>Item 1</sl-menu-item>
+      <sl-menu-item>Item 2</sl-menu-item>
+      <sl-menu-item>Item 3</sl-menu-item>
+    </sl-menu>
+  </sl-dropdown>
+</div>
+
+<style>
+  .dropdown-hoist {
+    border: solid 2px var(--sl-panel-border-color);
+    padding: var(--sl-spacing-medium);
+    overflow: hidden;
+  }
+</style>
+```
+
+```jsx react
+import { 
+  SlButton,
+  SlDivider,
+  SlDropdown,
+  SlIcon,
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .dropdown-hoist {
+    border: solid 2px var(--sl-panel-border-color);
+    padding: var(--sl-spacing-medium);
+    overflow: hidden;
+  }
+`;
+
+const App = () => (
+  <>
+    <div className="dropdown-hoist">
+      <SlDropdown>
+        <SlButton slot="trigger" caret>No Hoist</SlButton>
+        <SlMenu>
+          <SlMenuItem>Item 1</SlMenuItem>
+          <SlMenuItem>Item 2</SlMenuItem>
+          <SlMenuItem>Item 3</SlMenuItem>
+        </SlMenu>
+      </SlDropdown>
+
+      <SlDropdown hoist>
+        <SlButton slot="trigger" caret>Hoist</SlButton>
+        <SlMenu>
+          <SlMenuItem>Item 1</SlMenuItem>
+          <SlMenuItem>Item 2</SlMenuItem>
+          <SlMenuItem>Item 3</SlMenuItem>
+        </SlMenu>
+      </SlDropdown>
+    </div>
+
+    <style>{css}</style>
+  </>
+);
+```
+
+[component-metadata:sl-dropdown]

data/remote-src/2.0.0.beta64/shoelace-next/docs/components/format-bytes.md

@@ -0,0 +1,126 @@
+# Format Bytes
+
+[component-header:sl-format-bytes]
+
+Formats a number as a human readable bytes value.
+
+```html preview
+<div class="format-bytes-overview">
+  The file is <sl-format-bytes value="1000"></sl-format-bytes> in size.
+  <br><br>
+  <sl-input type="number" value="1000" label="Number to Format" style="max-width: 180px;"></sl-input>  
+</div>
+
+<script>
+  const container = document.querySelector('.format-bytes-overview');
+  const formatter = container.querySelector('sl-format-bytes');
+  const input = container.querySelector('sl-input');
+
+  input.addEventListener('sl-input', () => formatter.value = input.value || 0);
+</script>
+```
+
+
+```jsx react
+import { useState } from 'react';
+import { 
+  SlButton, 
+  SlFormatBytes, 
+  SlInput 
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [value, setValue] = useState(1000);
+
+  return (
+    <>
+      The file is <SlFormatBytes value={value} /> in size.
+      <br /><br />
+      <SlInput 
+        type="number" 
+        value={value}
+        label="Number to Format" 
+        style={{ maxWidth: '180px' }}
+        onSlInput={event => setValue(event.target.value)}
+      />
+    </>
+  );
+};
+```
+
+## Examples
+
+### Formatting Bytes
+
+Set the `value` attribute to a number to get the value in bytes.
+
+```html preview
+<sl-format-bytes value="12"></sl-format-bytes><br>
+<sl-format-bytes value="1200"></sl-format-bytes><br>
+<sl-format-bytes value="1200000"></sl-format-bytes><br>
+<sl-format-bytes value="1200000000"></sl-format-bytes>
+```
+
+
+```jsx react
+import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlFormatBytes value="12" /><br />
+    <SlFormatBytes value="1200" /><br />
+    <SlFormatBytes value="1200000" /><br />
+    <SlFormatBytes value="1200000000" />
+  </>
+);
+```
+
+### Formatting Bits
+
+To get the value in bits, set the `unit` attribute to `bits`.
+
+```html preview
+<sl-format-bytes value="12" unit="bits"></sl-format-bytes><br>
+<sl-format-bytes value="1200" unit="bits"></sl-format-bytes><br>
+<sl-format-bytes value="1200000" unit="bits"></sl-format-bytes><br>
+<sl-format-bytes value="1200000000" unit="bits"></sl-format-bytes>
+```
+
+```jsx react
+import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlFormatBytes value="12" unit="bits" /><br />
+    <SlFormatBytes value="1200" unit="bits" /><br />
+    <SlFormatBytes value="1200000" unit="bits" /><br />
+    <SlFormatBytes value="1200000000" unit="bits" />
+  </>
+);
+```
+
+### Localization
+
+Use the `lang` attribute to set the number formatting locale.
+
+```html preview
+<sl-format-bytes value="12" lang="de"></sl-format-bytes><br>
+<sl-format-bytes value="1200" lang="de"></sl-format-bytes><br>
+<sl-format-bytes value="1200000" lang="de"></sl-format-bytes><br>
+<sl-format-bytes value="1200000000" lang="de"></sl-format-bytes>
+```
+
+```jsx react
+import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlFormatBytes value="12" lang="de" /><br />
+    <SlFormatBytes value="1200" lang="de" /><br />
+    <SlFormatBytes value="1200000" lang="de" /><br />
+    <SlFormatBytes value="1200000000" lang="de" />
+  </>
+);
+```
+
+[component-metadata:sl-format-bytes]

data/remote-src/2.0.0.beta64/shoelace-next/docs/components/format-date.md

@@ -0,0 +1,120 @@
+# Format Date
+
+[component-header:sl-format-date]
+
+Formats a date/time using the specified locale and options.
+
+Localization is handled by the browser's [`Intl.DateTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). No language packs are required.
+
+```html preview
+<!-- Shoelace 2 release date 🎉 -->
+<sl-format-date date="2020-07-15T09:17:00-04:00"></sl-format-date>
+```
+
+```jsx react
+import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlFormatDate date="2020-07-15T09:17:00-04:00" />
+);
+```
+
+The `date` attribute determines the date/time to use when formatting. It must be a string that [`Date.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse) can interpret or a [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object set via JavaScript. If omitted, the current date/time will be assumed.
+
+?> When using strings, avoid ambiguous dates such as `03/04/2020` which can be interpreted as March 4 or April 3 depending on the user's browser and locale. Instead, always use a valid [ISO 8601 date time string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse#Date_Time_String_Format) to ensure the date will be parsed properly by all clients.
+
+## Examples
+
+### Date & Time Formatting
+
+Formatting options are based on those found in the [`Intl.DateTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). When formatting options are provided, the date/time will be formatted according to those values. When no formatting options are provided, a localized, numeric date will be displayed instead.
+
+```html preview
+<!-- Human-readable date -->
+<sl-format-date month="long" day="numeric" year="numeric"></sl-format-date><br>
+
+<!-- Time -->
+<sl-format-date hour="numeric" minute="numeric"></sl-format-date><br>
+
+<!-- Weekday -->
+<sl-format-date weekday="long"></sl-format-date><br>
+
+<!-- Month -->
+<sl-format-date month="long"></sl-format-date><br>
+
+<!-- Year -->
+<sl-format-date year="numeric"></sl-format-date><br>
+
+<!-- No formatting options -->
+<sl-format-date></sl-format-date>
+```
+
+```jsx react
+import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    {/* Human-readable date */}
+    <SlFormatDate month="long" day="numeric" year="numeric" /><br />
+
+    {/* Time */}
+    <SlFormatDate hour="numeric" minute="numeric" /><br />
+
+    {/* Weekday */}
+    <SlFormatDate weekday="long" /><br />
+
+    {/* Month */}
+    <SlFormatDate month="long" /><br />
+
+    {/* Year */}
+    <SlFormatDate year="numeric" /><br />
+
+    {/* No formatting options */}
+    <SlFormatDate />
+  </>
+);
+```
+
+### Hour Formatting
+
+By default, the browser will determine whether to use 12-hour or 24-hour time. To force one or the other, set the `hour-format` attribute to `12` or `24`.
+
+```html preview
+<sl-format-date hour="numeric" minute="numeric" hour-format="12"></sl-format-date><br>
+<sl-format-date hour="numeric" minute="numeric" hour-format="24"></sl-format-date>
+```
+
+```jsx react
+import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlFormatDate hour="numeric" minute="numeric" hour-format="12" /><br />
+    <SlFormatDate hour="numeric" minute="numeric" hour-format="24" />
+  </>
+);
+```
+
+### Localization
+
+Use the `lang` attribute to set the date/time formatting locale.
+
+```html preview
+English: <sl-format-date lang="en"></sl-format-date><br>
+French: <sl-format-date lang="fr"></sl-format-date><br>
+Russian: <sl-format-date lang="ru"></sl-format-date>
+```
+
+```jsx react
+import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    English: <SlFormatDate lang="en" /><br />
+    French: <SlFormatDate lang="fr" /><br />
+    Russian: <SlFormatDate lang="ru" />
+  </>
+);
+```
+
+[component-metadata:sl-format-date]