@cruglobal/cornerstone-components 0.1.0

package/dist/bundled/skills/cornerstone/references/components/slider.md

@@ -0,0 +1,544 @@
+# Slider
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/components/slider
+
+<style>
+  /* Vertical sliders need a container height and a narrow track column; 80px is exactly
+     `--cs-space-5xl`, and the row is four of them tall. */
+  .vertical-slider-row {
+    block-size: calc(var(--cs-space-5xl) * 4);
+  }
+
+  .vertical-slider {
+    inline-size: var(--cs-space-5xl);
+  }
+</style>
+
+```html
+<cs-slider
+  label="Number of users"
+  hint="Limit six per team"
+  name="value"
+  value="3"
+  min="0"
+  max="6"
+  with-markers
+  with-tooltip
+>
+  <span slot="reference">Less</span>
+  <span slot="reference">More</span>
+</cs-slider>
+```
+
+```html
+<cs-slider label="Number of users" hint="Limit six per team" value="3" min="0" max="6">
+  <span slot="reference">Less</span>
+  <span slot="reference">More</span>
+</cs-slider>
+```
+
+> **Info**
+>
+> This component works with standard `<form>` elements. See [form controls](https://cruglobal.github.io/cornerstone-design-system/form-controls) for form submission and client-side validation.
+
+## Examples
+
+### Label
+
+Use the `label` attribute to give the slider an accessible label. For labels that contain HTML, use the `label` slot instead.
+
+```html
+<cs-slider label="Volume" min="0" max="100"></cs-slider>
+```
+
+### Hint
+
+Add descriptive hint to a slider with the `hint` attribute. For hints that contain HTML, use the `hint` slot instead.
+
+```html
+<cs-slider label="Volume" hint="Controls the volume of the current song." min="0" max="100" value="50"></cs-slider>
+```
+
+### Min, Max & Step
+
+Use the `min` and `max` attributes to define the slider's range, and the `step` attribute to control the increment between values.
+
+```html
+<cs-slider label="Between zero and one" min="0" max="1" step="0.1" value="0.5" with-tooltip></cs-slider>
+```
+
+### Showing a Tooltip
+
+Use the `with-tooltip` attribute to display a tooltip with the current value when the slider is focused or being dragged.
+
+```html
+<cs-slider label="Quality" name="quality" min="0" max="100" value="50" with-tooltip></cs-slider>
+```
+
+### Showing Markers
+
+Use the `with-markers` attribute to display visual indicators at each step increment. This works best with sliders that have a smaller range of values.
+
+```html
+<cs-slider label="Size" name="size" min="0" max="8" value="4" with-markers></cs-slider>
+```
+
+### Adding References
+
+Use the `reference` slot to add contextual labels below the slider. References are automatically spaced using `space-between`, making them easy to align with the start, center, and end positions.
+
+```html
+<cs-slider
+  label="Speed"
+  name="speed"
+  min="1"
+  max="5"
+  value="3"
+  with-markers
+  hint="Controls the speed of the thing you're currently doing."
+>
+  <span slot="reference">Slow</span>
+  <span slot="reference">Medium</span>
+  <span slot="reference">Fast</span>
+</cs-slider>
+```
+
+> **Info**
+>
+> <strong>Show a reference next to a specific marker.</strong><br />
+> Add `position: absolute` to the reference and set `left`, `right`, `top`, or `bottom` to a percentage that matches the marker's position.
+
+### Range Selection
+
+Use the `range` attribute to enable dual-thumb selection for choosing a range of values. Set the initial thumb positions with the `min-value` and `max-value` attributes.
+
+```html
+<cs-slider
+  label="Price Range"
+  hint="Select minimum and maximum price"
+  name="price"
+  range
+  min="0"
+  max="100"
+  min-value="20"
+  max-value="80"
+  with-tooltip
+  id="slider__range"
+>
+  <span slot="reference">$0</span>
+  <span slot="reference">$50</span>
+  <span slot="reference">$100</span>
+</cs-slider>
+
+<script type="module">
+  const slider = document.getElementById('slider__range');
+  const formatter = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 });
+
+  customElements.whenDefined('cs-slider').then(() => {
+    slider.valueFormatter = value => formatter.format(value);
+  });
+</script>
+```
+
+For range sliders, the `minValue` and `maxValue` properties represent the current positions of the thumbs. When the form is submitted, both values will be included as separate entries with the same name.
+
+```ts
+const slider = document.querySelector('cs-slider[range]');
+
+// Get the current values
+console.log(`Min value: ${slider.minValue}, Max value: ${slider.maxValue}`);
+
+// Set the values programmatically
+slider.minValue = 30;
+slider.maxValue = 70;
+```
+
+### Vertical Sliders
+
+Set the `orientation` attribute to `vertical` to create a vertical slider. Vertical sliders automatically center themselves and fill the available vertical space.
+
+```html
+<div class="cs-cluster cs-align-items-stretch">
+  <cs-slider orientation="vertical" label="Volume" name="volume" value="65" class="vertical-slider"></cs-slider>
+
+  <cs-slider orientation="vertical" label="Bass" name="bass" value="50" class="vertical-slider"></cs-slider>
+
+  <cs-slider orientation="vertical" label="Treble" name="treble" value="40" class="vertical-slider"></cs-slider>
+</div>
+```
+
+Range sliders can also be vertical.
+
+```html
+<div class="cs-cluster cs-gap-xl vertical-slider-row">
+  <cs-slider
+    label="Temperature Range"
+    orientation="vertical"
+    range
+    min="0"
+    max="100"
+    min-value="30"
+    max-value="70"
+    with-tooltip
+    tooltip-placement="right"
+    id="slider__vertical-range"
+  >
+  </cs-slider>
+</div>
+
+<script type="module">
+  const slider = document.getElementById('slider__vertical-range');
+  slider.valueFormatter = value => {
+    return new Intl.NumberFormat('en', {
+      style: 'unit',
+      unit: 'fahrenheit',
+      unitDisplay: 'short',
+      minimumFractionDigits: 0,
+      maximumFractionDigits: 1,
+    }).format(value);
+  };
+</script>
+```
+
+### Size
+
+Control the slider's size with the `size` attribute. Valid options are `xs`, `s`, `m`, `l`, and `xl`.
+
+```html
+<div class="cs-stack">
+  <cs-slider size="xs" value="50" label="Extra small"></cs-slider>
+  <cs-slider size="s" value="50" label="Small"></cs-slider>
+  <cs-slider size="m" value="50" label="Medium"></cs-slider>
+  <cs-slider size="l" value="50" label="Large"></cs-slider>
+  <cs-slider size="xl" value="50" label="Extra large"></cs-slider>
+</div>
+```
+
+### Indicator Offset
+
+By default, the filled indicator extends from the minimum value to the current position. Use the `indicator-offset` attribute to change the starting point of this visual indicator.
+
+```html
+<cs-slider
+  label="User Friendliness"
+  hint="Did you find our product easy to use?"
+  name="value"
+  value="0"
+  min="-5"
+  max="5"
+  indicator-offset="0"
+  with-markers
+  with-tooltip
+>
+  <span slot="reference">Easy</span>
+  <span slot="reference">Moderate</span>
+  <span slot="reference">Difficult</span>
+</cs-slider>
+```
+
+### Disabled
+
+Use the `disabled` attribute to disable a slider.
+
+```html
+<cs-slider label="Disabled" value="50" disabled></cs-slider>
+```
+
+### Readonly
+
+Use the `readonly` attribute to show a value that users can't change by dragging. Unlike `disabled`, a readonly slider stays focusable and its value is still submitted with the form.
+
+```html
+<cs-slider label="Server load" value="72" min="0" max="100" with-tooltip readonly></cs-slider>
+```
+
+### Formatting the Value
+
+Customize how values are displayed in tooltips and announced to screen readers using the `valueFormatter` property. Set it to a function that accepts a number and returns a formatted string. The [`Intl.NumberFormat API`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) is particularly useful for this.
+
+```html
+<!-- Percent -->
+<cs-slider
+  id="slider__percent"
+  label="Percentage"
+  name="percentage"
+  value="0.5"
+  min="0"
+  max="1"
+  step=".01"
+  with-tooltip
+></cs-slider
+><br />
+
+<script type="module">
+  const slider = document.getElementById('slider__percent');
+  const formatter = new Intl.NumberFormat('en-US', { style: 'percent' });
+
+  customElements.whenDefined('cs-slider').then(() => {
+    slider.valueFormatter = value => formatter.format(value);
+  });
+</script>
+
+<!-- Duration -->
+<cs-slider id="slider__duration" label="Duration" name="duration" value="12" min="0" max="24" with-tooltip></cs-slider
+><br />
+
+<script type="module">
+  const slider = document.getElementById('slider__duration');
+  const formatter = new Intl.NumberFormat('en-US', { style: 'unit', unit: 'hour', unitDisplay: 'long' });
+
+  customElements.whenDefined('cs-slider').then(() => {
+    slider.valueFormatter = value => formatter.format(value);
+  });
+</script>
+
+<!-- Currency -->
+<cs-slider id="slider__currency" label="Currency" name="currency" min="0" max="100" value="50" with-tooltip></cs-slider>
+
+<script type="module">
+  const slider = document.getElementById('slider__currency');
+  const formatter = new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+    currencyDisplay: 'symbol',
+    maximumFractionDigits: 0,
+  });
+
+  customElements.whenDefined('cs-slider').then(() => {
+    slider.valueFormatter = value => formatter.format(value);
+  });
+</script>
+```
+
+### Reacting to Input
+
+The slider emits an `input` event as the user drags, so you can drive live UI from its value in real time. Here, moving the slider resizes the preview text.
+
+```html
+<div class="text-size-demo">
+  <p class="text-size-preview">The quick brown fox jumps over the lazy dog.</p>
+
+  <cs-divider></cs-divider>
+
+  <cs-slider label="Text size" min="12" max="48" value="18" with-tooltip></cs-slider>
+</div>
+
+<script type="module">
+  const demo = document.querySelector('.text-size-demo');
+  const slider = demo.querySelector('cs-slider');
+  const preview = demo.querySelector('.text-size-preview');
+
+  slider.addEventListener('input', () => {
+    preview.style.fontSize = `${slider.value}px`;
+  });
+</script>
+
+<style>
+  .text-size-demo .text-size-preview {
+    margin: 0 0 var(--cs-space-m);
+    font-size: 18px;
+    transition: font-size 75ms ease;
+  }
+</style>
+```
+
+### Filtering with a Range
+
+A range slider's two thumbs make it a natural filter control. Here, dragging the thumbs hides list items whose price falls outside the selected range.
+
+```html
+<div class="price-filter-demo">
+  <ul class="price-filter-list">
+    <li data-price="15">Sticker pack — $15</li>
+    <li data-price="30">T-shirt — $30</li>
+    <li data-price="55">Hoodie — $55</li>
+    <li data-price="80">Backpack — $80</li>
+    <li data-price="120">Jacket — $120</li>
+  </ul>
+
+  <cs-divider></cs-divider>
+
+  <cs-slider
+    id="price-filter"
+    label="Price range"
+    range
+    min="0"
+    max="150"
+    min-value="0"
+    max-value="150"
+    with-tooltip
+  ></cs-slider>
+</div>
+
+<script type="module">
+  const demo = document.querySelector('.price-filter-demo');
+  const slider = demo.querySelector('cs-slider');
+  const items = demo.querySelectorAll('.price-filter-list li');
+  const currency = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD', maximumFractionDigits: 0 });
+
+  function filter() {
+    items.forEach(item => {
+      const price = Number(item.dataset.price);
+      item.hidden = price < slider.minValue || price > slider.maxValue;
+    });
+  }
+
+  customElements.whenDefined('cs-slider').then(() => {
+    slider.valueFormatter = value => currency.format(value);
+    slider.addEventListener('input', filter);
+    filter();
+  });
+</script>
+
+<style>
+  .price-filter-demo .price-filter-list {
+    list-style: none;
+    margin: 0 0 var(--cs-space-m);
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--cs-space-xs);
+    min-height: 13rem;
+  }
+
+  .price-filter-demo .price-filter-list li {
+    padding: var(--cs-space-xs) var(--cs-space-s);
+    border-radius: var(--cs-border-radius-m);
+    background-color: color-mix(in srgb, var(--cs-color-brand-fill-loud) 10%, transparent);
+  }
+</style>
+```
+
+## API
+
+### Importing
+
+If you're using the autoloader or a hosted project, components load on demand — no manual import
+needed. To cherry-pick this component, use one of the following snippets.
+
+**npm**
+
+```js
+import '@cruglobal/cornerstone-components/components/slider/slider.js';
+```
+
+**Self-Hosted**
+
+```js
+import './cornerstone/components/slider/slider.js';
+```
+
+**React**
+
+```js
+import CsSlider from '@cruglobal/cornerstone-components/react/slider/index.js';
+```
+
+### Slots
+
+Valid slot names for this component (use exactly these — any other `slot` value is silently ignored and the element falls back to the default slot):
+
+- `hint` — Text that describes how to use the input. Alternatively, you can use the `hint` attribute. instead.
+- `label` — The slider label. Alternatively, you can use the `label` attribute.
+- `reference` — One or more reference labels to show visually below the slider.
+
+### Attributes & Properties
+
+| Property | Attribute | Description | Type | Default | Reflects |
+| --- | --- | --- | --- | --- | --- |
+| `autofocus` | `autofocus` | Tells the browser to focus the slider when the page loads or a dialog is shown. | `boolean` | — | — |
+| `defaultValue` | `value` | The default value of the form control. Primarily used for resetting the form control. | `number` | — | Yes |
+| `disabled` | `disabled` | Disables the slider. | `boolean` | `false` | — |
+| `form` | — | By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you to place the form control outside of a form and associate it with the form that has this `id`. The form must be in the same document or shadow root for this to work. | `HTMLFormElement \| null` | — | — |
+| `hint` | `hint` | The slider hint. If you need to display HTML, use the hint slot instead. | `string` | `''` | — |
+| `indicatorOffset` | `indicator-offset` | The starting value from which to draw the slider's fill, which is based on its current value. | `number` | — | — |
+| `isRange` | — | Get if this is a range slider | `boolean` | — | — |
+| `label` | `label` | The slider's label. If you need to provide HTML in the label, use the `label` slot instead. | `string` | `''` | — |
+| `max` | `max` | The maximum value allowed. | `number` | `100` | — |
+| `maxValue` | `max-value` | The maximum value of a range selection. Used only when range attribute is set. | `number` | `50` | — |
+| `min` | `min` | The minimum value allowed. | `number` | `0` | — |
+| `minValue` | `min-value` | The minimum value of a range selection. Used only when range attribute is set. | `number` | `0` | — |
+| `name` | `name` | The name of the slider. This will be submitted with the form as a name/value pair. | `string \| null` | `null` | Yes |
+| `orientation` | `orientation` | The orientation of the slider. | `'horizontal' \| 'vertical'` | `'horizontal'` | Yes |
+| `range` | `range` | Converts the slider to a range slider with two thumbs. | `boolean` | `false` | Yes |
+| `readonly` | `readonly` | Makes the slider a read-only field. | `boolean` | `false` | Yes |
+| `size` | `size` | The slider's size. | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` | `'m'` | Yes |
+| `ssrHint` | `ssr-hint` | Only required for SSR. Set to `true` if you're slotting in a `hint` element so the server-rendered markup includes the hint before the component hydrates on the client. | `boolean` | `false` | — |
+| `ssrLabel` | `ssr-label` | Only required for SSR. Set to `true` if you're slotting in a `label` element so the server-rendered markup includes the label before the component hydrates on the client. | `boolean` | `false` | — |
+| `ssrReference` | `ssr-reference` | Only required for SSR. Set to `true` if you're slotting in a `reference` element. | `boolean` | `false` | — |
+| `step` | `step` | The granularity the value must adhere to when incrementing and decrementing. | `number` | `1` | — |
+| `tooltipDistance` | `tooltip-distance` | The distance of the tooltip from the slider's thumb. | `number` | `8` | — |
+| `tooltipPlacement` | `tooltip-placement` | The placement of the tooltip in reference to the slider's thumb. | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Yes |
+| `validationTarget` | — | Override validation target to point to the focusable element | `undefined \| HTMLElement` | — | — |
+| `validators` | — | Validators are static because they have `observedAttributes`, essentially attributes to "watch" for changes. Whenever these attributes change, we want to be notified and update the validator. | `Validator[]` | `[]` | — |
+| `value` | — | The current value of the slider, submitted as a name/value pair with form data. | `number` | — | — |
+| `valueFormatter` | — | A custom formatting function to apply to the value. This will be shown in the tooltip and announced by screen readers. Must be set with JavaScript. Property only. | `(value: number) => string` | — | — |
+| `withMarkers` | `with-markers` | Draws markers at each step along the slider. | `boolean` | `false` | — |
+| `withTooltip` | `with-tooltip` | Draws a tooltip above the thumb when the control has focus or is dragged. | `boolean` | `false` | — |
+
+### Methods
+
+| Name | Description | Arguments |
+| --- | --- | --- |
+| `blur()` | Removes focus from the slider. | — |
+| `focus()` | Sets focus to the slider. | — |
+| `formStateRestoreCallback()` | Called when the browser is trying to restore element’s state to state in which case reason is "restore", or when the browser is trying to fulfill autofill on behalf of user in which case reason is "autocomplete". In the case of "restore", state is a string, File, or FormData object previously set as the second argument to setFormValue. | `state: string \| File \| FormData \| null, reason: 'autocomplete' \| 'restore'` |
+| `resetValidity()` | Reset validity is a way of removing manual custom errors and native validation. | — |
+| `setCustomValidity()` | Do not use this when creating a "Validator". This is intended for end users of components. We track manually defined custom errors so we don't clear them on accident in our validators. | `message: string` |
+| `stepDown()` | Decreases the slider's value by `step`. This is a programmatic change, so `input` and `change` events will not be emitted when this is called. | — |
+| `stepUp()` | Increases the slider's value by `step`. This is a programmatic change, so `input` and `change` events will not be emitted when this is called. | — |
+
+### Events
+
+| Name | Description |
+| --- | --- |
+| `blur` | Emitted when the control loses focus. |
+| `change` | Emitted when an alteration to the control's value is committed by the user. |
+| `cs-invalid` | Emitted when the form control has been checked for validity and its constraints aren't satisfied. |
+| `focus` | Emitted when the control gains focus. |
+| `input` | Emitted when the control receives input. |
+
+### CSS Custom Properties
+
+| Name | Description | Default |
+| --- | --- | --- |
+| `--marker-height` | The height of each individual marker. | `0.1875em` |
+| `--marker-width` | The width of each individual marker. | `0.1875em` |
+| `--thumb-height` | The height of the thumb. | `1.25em` |
+| `--thumb-width` | The width of the thumb. | `1.25em` |
+| `--track-size` | The height or width of the slider's track. | `0.75em` |
+
+### Custom States
+
+| Name | Description | CSS selector |
+| --- | --- | --- |
+| `disabled` | Applied when the slider is disabled. | `:state(disabled)` |
+| `dragging` | Applied when the slider is being dragged. | `:state(dragging)` |
+| `focused` | Applied when the slider has focus. | `:state(focused)` |
+| `user-invalid` | Applied when the slider is invalid and the user has sufficiently interacted with it. | `:state(user-invalid)` |
+| `user-valid` | Applied when the slider is valid and the user has sufficiently interacted with it. | `:state(user-valid)` |
+
+### CSS Parts
+
+| Name | Description | CSS selector |
+| --- | --- | --- |
+| `hint` | The element that contains the slider's description. | `::part(hint)` |
+| `indicator` | The colored indicator that shows from the start of the slider to the current value. | `::part(indicator)` |
+| `label` | The element that contains the sliders's label. | `::part(label)` |
+| `marker` | The individual markers that are shown when `with-markers` is used. | `::part(marker)` |
+| `markers` | The container that holds all the markers when `with-markers` is used. | `::part(markers)` |
+| `references` | The container that holds references that get slotted in. | `::part(references)` |
+| `slider` | The focusable element with `role="slider"`. Contains the track and reference slot. | `::part(slider)` |
+| `thumb` | The slider's thumb. | `::part(thumb)` |
+| `thumb-max` | The max value thumb in a range slider. | `::part(thumb-max)` |
+| `thumb-min` | The min value thumb in a range slider. | `::part(thumb-min)` |
+| `tooltip` | The tooltip, a `<cs-tooltip>` element. | `::part(tooltip)` |
+| `tooltip__arrow` | The tooltip's `arrow` part. | `::part(tooltip__arrow)` |
+| `tooltip__body` | The tooltip's `body` part. | `::part(tooltip__body)` |
+| `tooltip__tooltip` | The tooltip's `tooltip` part. | `::part(tooltip__tooltip)` |
+| `track` | The slider's track. | `::part(track)` |
+
+### Dependencies
+
+- `<cs-popup>`
+- `<cs-tooltip>`

package/dist/bundled/skills/cornerstone/references/components/spinner.md

@@ -0,0 +1,83 @@
+# Spinner
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/components/spinner
+
+```html
+<cs-spinner></cs-spinner>
+```
+
+## Examples
+
+### Size
+
+Spinners are sized based on the current font size. To change the size, set `font-size` on the spinner itself or on a parent element.
+
+```html
+<cs-spinner></cs-spinner>
+<cs-spinner class="cs-font-size-2xl"></cs-spinner>
+<cs-spinner class="cs-font-size-4xl"></cs-spinner>
+```
+
+### Track Width
+
+Use the `--track-width` custom property to change the thickness of the spinner's track.
+
+```html
+<cs-spinner class="cs-font-size-4xl" style="--track-width: 10px;"></cs-spinner>
+```
+
+### Colors
+
+Use the `--track-color` and `--indicator-color` custom properties to recolor the spinner.
+
+```html
+<cs-spinner class="cs-font-size-4xl" style="--indicator-color: var(--cs-color-success-fill-loud); --track-color: var(--cs-color-success-fill-quiet);"></cs-spinner>
+```
+
+### Speed
+
+Use the `--speed` custom property to set how long one full rotation takes.
+
+```html
+<cs-spinner class="cs-font-size-4xl" style="--speed: 4s;"></cs-spinner>
+```
+
+## API
+
+### Importing
+
+If you're using the autoloader or a hosted project, components load on demand — no manual import
+needed. To cherry-pick this component, use one of the following snippets.
+
+**npm**
+
+```js
+import '@cruglobal/cornerstone-components/components/spinner/spinner.js';
+```
+
+**Self-Hosted**
+
+```js
+import './cornerstone/components/spinner/spinner.js';
+```
+
+**React**
+
+```js
+import CsSpinner from '@cruglobal/cornerstone-components/react/spinner/index.js';
+```
+
+### CSS Custom Properties
+
+| Name | Description | Default |
+| --- | --- | --- |
+| `--indicator-color` | The color of the spinner's indicator. | — |
+| `--speed` | The time it takes for the spinner to complete one animation cycle. | — |
+| `--track-color` | The color of the track. | — |
+| `--track-width` | The width of the track. | — |
+
+### CSS Parts
+
+| Name | Description | CSS selector |
+| --- | --- | --- |
+| `spinner` | The component's outer wrapper. | `::part(spinner)` |