@cruglobal/cornerstone-components 0.1.0

package/dist/unbundled/skills/cornerstone/references/components/copy-button.md

@@ -0,0 +1,269 @@
+# Copy Button
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/components/copy-button
+
+```html
+<cs-copy-button value="https://github.com/CruGlobal/cornerstone-design-system"></cs-copy-button>
+```
+
+> **Info**
+>
+> <strong>Copying requires a secure context.</strong><br />
+> Copy buttons use the browser's [`clipboard.writeText()`](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText) method, which requires a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (HTTPS) in most browsers.
+
+## Examples
+
+### Copying from Other Elements
+
+Set the `value` attribute to copy a literal string, or point the `from` attribute at another element's `id` to copy live content. When both are present, `from` wins.
+
+By default `from` copies the target's [`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent). Add a modifier to copy an attribute or property instead:
+
+| Syntax            | Copies                      | Example                 |
+| ----------------- | --------------------------- | ----------------------- |
+| `from="id"`       | The element's `textContent` | `from="my-phone"`       |
+| `from="id[attr]"` | The named attribute         | `from="my-link[href]"`  |
+| `from="id.prop"`  | The named property          | `from="my-input.value"` |
+
+```html
+<div class="cs-stack">
+  <!-- Copies the span's textContent -->
+  <div class="cs-cluster cs-align-items-center cs-gap-2xs">
+    <span id="my-phone">+1 (234) 456-7890</span>
+    <cs-copy-button from="my-phone"></cs-copy-button>
+  </div>
+
+  <!-- Copies the input's "value" property -->
+  <div class="cs-cluster cs-align-items-center cs-gap-2xs">
+    <cs-input id="my-input" type="text" value="User input" style="max-width: 300px;"></cs-input>
+    <cs-copy-button from="my-input.value"></cs-copy-button>
+  </div>
+
+  <!-- Copies the link's "href" attribute -->
+  <div class="cs-cluster cs-align-items-center cs-gap-2xs">
+    <a id="my-link" href="https://github.com/CruGlobal/cornerstone-design-system">Cornerstone on GitHub</a>
+    <cs-copy-button from="my-link[href]"></cs-copy-button>
+  </div>
+</div>
+```
+
+### Custom Labels
+
+The copy button shows a tooltip on hover and focus, then briefly swaps it to confirm a copy. Set the `copy-label`, `success-label`, and `error-label` attributes to customize the text for each state. `copy-label` also serves as the button's accessible name.
+
+```html
+<cs-copy-button
+  value="Custom labels are easy"
+  copy-label="Click to copy"
+  success-label="You did it!"
+  error-label="Whoops, your browser doesn't support this!"
+></cs-copy-button>
+```
+
+### Custom Icons
+
+Use the `copy-icon`, `success-icon`, and `error-icon` slots to replace the icon shown in each state. [`<cs-icon>`](https://cruglobal.github.io/cornerstone-design-system/components/icon) works best, but any image will do.
+
+```html
+<cs-copy-button value="Copied from a custom button">
+  <cs-icon slot="copy-icon" name="content_paste"></cs-icon>
+  <cs-icon slot="success-icon" name="thumb_up" variant="fill"></cs-icon>
+  <cs-icon slot="error-icon" name="close"></cs-icon>
+</cs-copy-button>
+```
+
+### Custom Trigger
+
+By default the copy button renders an icon-only button. Slot in any clickable element to use as the trigger instead — a Cornerstone button, a native button, or anything else.
+
+```html
+<div class="cs-stack">
+  <cs-copy-button value="You can copy anything with a custom trigger!">
+    <cs-button appearance="filled">Copy to Clipboard</cs-button>
+  </cs-copy-button>
+
+  <cs-copy-button value="https://github.com/CruGlobal/cornerstone-design-system">
+    <button type="button" class="cs-filled">Copy to Clipboard</button>
+  </cs-copy-button>
+</div>
+```
+
+> **Info**
+>
+> <strong>Custom triggers get the same feedback with no extra wiring.</strong><br />
+> They receive the same tooltip and copy feedback as the default trigger; the icon swap is the one piece unique to it. Set `tooltip="none"` to opt out of the tooltip, and listen for the `cs-copy` and `cs-error` events or style the `:state(success)` and `:state(error)` custom states for your own feedback.
+
+### Disabled
+
+Add the `disabled` attribute to turn off the copy button.
+
+```html
+<cs-copy-button value="You can't copy me" disabled></cs-copy-button>
+```
+
+### Handling Errors
+
+A copy fails when `value` is empty, when `from` points to an id that doesn't exist, or when the browser rejects the operation. Either way, the button shows its error state and emits the `cs-error` event. Customize the message with `error-label` and the icon with the `error-icon` slot.
+
+```html
+<cs-copy-button from="i-do-not-exist"></cs-copy-button>
+```
+
+### Feedback Duration
+
+After a copy, the tooltip briefly shows the success or error label. Set the `feedback-duration` attribute (in milliseconds) to control how long it stays visible.
+
+```html
+<cs-copy-button value="Cornerstone rocks!" feedback-duration="250"></cs-copy-button>
+```
+
+### Tooltip Mode
+
+The `tooltip` attribute controls when the built-in tooltip appears, on both the default and custom triggers.
+
+| Value                                                                            | Behavior                                                        |
+| -------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `full` <cs-badge appearance="outlined" variant="neutral" pill>default</cs-badge> | Shows on hover and focus, and reused for copy feedback          |
+| `copy`                                                                           | Stays silent on hover and focus; appears only to confirm a copy |
+| `none`                                                                           | Never shown                                                     |
+
+```html
+<div class="cs-cluster">
+  <cs-copy-button value="npm install @cruglobal/cornerstone-components" tooltip="full"></cs-copy-button>
+  <cs-copy-button value="npm install @cruglobal/cornerstone-components" tooltip="copy"></cs-copy-button>
+  <cs-copy-button value="npm install @cruglobal/cornerstone-components" tooltip="none"></cs-copy-button>
+</div>
+```
+
+### Tooltip Placement
+
+The tooltip sits above the trigger by default. Set the `tooltip-placement` attribute to `top`, `right`, `bottom`, or `left` to move it.
+
+```html
+<div class="cs-cluster">
+  <cs-copy-button value="Above" tooltip-placement="top"></cs-copy-button>
+  <cs-copy-button value="Right" tooltip-placement="right"></cs-copy-button>
+  <cs-copy-button value="Below" tooltip-placement="bottom"></cs-copy-button>
+  <cs-copy-button value="Left" tooltip-placement="left"></cs-copy-button>
+</div>
+```
+
+### Customizing
+
+Style the button through its CSS parts — `button`, `copy-icon`, `success-icon`, and `error-icon` — to match your design.
+
+```html
+<cs-copy-button value="I'm so stylish" class="custom-styles">
+  <cs-icon slot="copy-icon" name="content_paste"></cs-icon>
+  <cs-icon slot="success-icon" name="thumb_up" variant="fill"></cs-icon>
+  <cs-icon slot="error-icon" name="thumb_down" variant="fill"></cs-icon>
+</cs-copy-button>
+
+<style>
+  .custom-styles,
+  .custom-styles::part(success-icon),
+  .custom-styles::part(error-icon) {
+    color: var(--cs-color-pink-95);
+  }
+
+  .custom-styles::part(button) {
+    background-color: var(--cs-color-pink-40);
+    border: solid var(--cs-border-width-m) var(--cs-color-pink-60);
+    border-right-color: var(--cs-color-pink-20);
+    border-bottom-color: var(--cs-color-pink-20);
+    border-radius: var(--cs-border-radius-m);
+    transition: all var(--cs-transition-slow) var(--cs-transition-easing);
+  }
+
+  .custom-styles::part(button):hover {
+    transform: scale(1.05);
+  }
+
+  .custom-styles::part(button):active {
+    transform: translateY(var(--cs-space-3xs));
+  }
+
+  .custom-styles::part(button):focus-visible {
+    outline: dashed var(--cs-border-width-m) var(--cs-color-pink-60);
+    outline-offset: var(--cs-space-2xs);
+  }
+</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/copy-button/copy-button.js';
+```
+
+**Self-Hosted**
+
+```js
+import './cornerstone/components/copy-button/copy-button.js';
+```
+
+**React**
+
+```js
+import CsCopyButton from '@cruglobal/cornerstone-components/react/copy-button/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):
+
+- `(default)` — The trigger element. By default, a copy icon button is rendered so this is optional. If desired, you can slot in a custom element such as `<cs-button>` or `<button>`.
+- `copy-icon` — The icon to show in the default copy state. Works best with `<cs-icon>`.
+- `error-icon` — The icon to show when a copy error occurs. Works best with `<cs-icon>`.
+- `success-icon` — The icon to show when the content is copied. Works best with `<cs-icon>`.
+
+### Attributes & Properties
+
+| Property | Attribute | Description | Type | Default | Reflects |
+| --- | --- | --- | --- | --- | --- |
+| `copyLabel` | `copy-label` | A custom label to use as the accessible name and tooltip text in the default copy state. | `string` | `''` | — |
+| `disabled` | `disabled` | Disables the copy button. | `boolean` | `false` | Yes |
+| `errorLabel` | `error-label` | A custom label to show in the tooltip when a copy error occurs. | `string` | `''` | — |
+| `feedbackDuration` | `feedback-duration` | The length of time to show feedback before restoring the default trigger. | `number` | `1000` | — |
+| `from` | `from` | An id that references an element in the same document from which data will be copied. If both this and `value` are present, this value will take precedence. By default, the target element's `textContent` will be copied. To copy an attribute, append the attribute name wrapped in square brackets, e.g. `from="el[value]"`. To copy a property, append a dot and the property name, e.g. `from="el.value"`. | `string` | `''` | — |
+| `successLabel` | `success-label` | A custom label to show in the tooltip after copying. | `string` | `''` | — |
+| `tooltip` | `tooltip` | Controls the built-in tooltip. `full` (default) shows the tooltip on hover and focus and during copy feedback. `copy` keeps the tooltip silent on hover/focus and only shows it briefly to confirm a successful or failed copy. `none` disables the tooltip entirely. Applies to both the default and custom triggers. | `'full' \| 'copy' \| 'none'` | `'full'` | Yes |
+| `tooltipPlacement` | `tooltip-placement` | The preferred placement of the tooltip. | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Yes |
+| `value` | `value` | The text value to copy. | `string` | `''` | — |
+
+### Events
+
+| Name | Description |
+| --- | --- |
+| `cs-copy` | Emitted when the data has been copied. |
+| `cs-error` | Emitted when the data could not be copied. |
+
+### Custom States
+
+| Name | Description | CSS selector |
+| --- | --- | --- |
+| `error` | Applied when the copy operation fails. | `:state(error)` |
+| `success` | Applied when the copy operation succeeds. | `:state(success)` |
+
+### CSS Parts
+
+| Name | Description | CSS selector |
+| --- | --- | --- |
+| `button` | The internal `<button>` element. | `::part(button)` |
+| `copy-icon` | The container that holds the copy icon. | `::part(copy-icon)` |
+| `error-icon` | The container that holds the error icon. | `::part(error-icon)` |
+| `feedback` | The internal `<cs-tooltip>` element. | `::part(feedback)` |
+| `success-icon` | The container that holds the success icon. | `::part(success-icon)` |
+
+### Dependencies
+
+- `<cs-icon>`
+- `<cs-popup>`
+- `<cs-tooltip>`

package/dist/unbundled/skills/cornerstone/references/components/details.md

@@ -0,0 +1,240 @@
+# Details
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/components/details
+
+```html
+<cs-details summary="Toggle Me">
+  Click the summary to expand and collapse the details component. You can put any content in here that you want to
+  reveal on demand!
+</cs-details>
+```
+
+## Examples
+
+### Expanded Initially
+
+Use the `open` attribute to expand the details initially.
+
+```html
+<cs-details summary="Toggle Me" open>
+  This details component is expanded by default. Users can click the summary to collapse it if they want to hide the
+  content.
+</cs-details>
+```
+
+### Disabled
+
+Use the `disabled` attribute to prevent the details from expanding.
+
+```html
+<cs-details summary="Disabled" disabled>
+  This content can't be seen because the details component is disabled. Try removing the disabled attribute to reveal
+  what's inside!
+</cs-details>
+```
+
+### Expand & Collapse Icons
+
+Use the `expand-icon` and `collapse-icon` slots to change the expand and collapse icons, respectively. To disable the animation, override the `rotate` property on the `icon` part as shown below.
+
+```html
+<cs-details summary="Toggle Me" class="custom-icons">
+  <cs-icon name="add_box" slot="expand-icon"></cs-icon>
+  <cs-icon name="indeterminate_check_box" slot="collapse-icon"></cs-icon>
+
+  This example uses custom plus and minus icons for expanding and collapsing. You can use any icon you want to match the
+  look and feel of your app.
+</cs-details>
+
+<style>
+  /* Disable the expand/collapse animation */
+  cs-details.custom-icons::part(icon) {
+    rotate: none;
+  }
+</style>
+```
+
+### Icon Placement
+
+The default position for the expand and collapse icons is at the end of the summary. Set the `icon-placement` attribute to `start` to place the icon at the start of the summary.
+
+```html
+<div class="cs-stack">
+  <cs-details summary="Start" icon-placement="start">
+    The expand/collapse icon is at the start of the summary. This is a common pattern that feels familiar to users who
+    are used to tree views and file explorers.
+  </cs-details>
+  <cs-details summary="End" icon-placement="end">
+    The expand/collapse icon is at the end of the summary. This is the default placement and works great for most use
+    cases.
+  </cs-details>
+</div>
+```
+
+### HTML in Summary
+
+To use HTML in the summary, use the `summary` slot.
+Links and other interactive elements will still retain their behavior:
+
+```html
+<cs-details>
+  <span slot="summary">
+    Some text
+    <a href="https://github.com/CruGlobal/cornerstone-design-system" target="_blank">a link</a>
+    more text
+  </span>
+
+  You can use the summary slot to put HTML in the summary, including links and other interactive elements. Pretty neat,
+  right?
+</cs-details>
+```
+
+### Right-to-Left Languages
+
+The details component, including its `icon-placement`, automatically adapts to right-to-left languages:
+
+```html
+<div class="cs-stack">
+  <cs-details summary="تبديلني" lang="ar" dir="rtl">
+    استخدام طريقة لوريم إيبسوم لأنها تعطي توزيعاَ طبيعياَ -إلى حد ما- للأحرف عوضاً عن
+  </cs-details>
+  <cs-details summary="تبديلني" lang="ar" dir="rtl" icon-placement="start">
+    استخدام طريقة لوريم إيبسوم لأنها تعطي توزيعاَ طبيعياَ -إلى حد ما- للأحرف عوضاً عن
+  </cs-details>
+</div>
+```
+
+### Appearance
+
+Use the `appearance` attribute to change the element’s visual appearance.
+
+```html
+<div class="cs-stack">
+  <cs-details summary="Outlined (default)">
+    This is the default outlined appearance. It has a subtle border that helps it stand out without being too flashy.
+  </cs-details>
+  <cs-details summary="Filled-outlined" appearance="filled-outlined">
+    The filled-outlined appearance combines a filled header with an outlined body. It gives the summary a bit more
+    visual weight while keeping the content area clean.
+  </cs-details>
+  <cs-details summary="Filled" appearance="filled">
+    The filled appearance adds a background color to the entire component. Use this when you want the details to really
+    pop on the page.
+  </cs-details>
+  <cs-details summary="Plain" appearance="plain">
+    No bells and whistles on this one. The plain appearance strips away borders and backgrounds for a minimalist look.
+  </cs-details>
+</div>
+```
+
+### Grouping Details
+
+Use the `name` attribute to create accordion-like behavior where only one details element with the same name can be open at a time. This matches the behavior of native `<details>` elements.
+
+```html
+<div class="cs-stack">
+  <cs-details name="group-1" summary="Section 1" open>
+    This is the first section of the accordion. When you open another section, this one will close automatically. Give
+    it a try!
+  </cs-details>
+
+  <cs-details name="group-1" summary="Section 2">
+    This is the second section. Notice how the first section closed when you opened this one? That's the accordion
+    behavior in action, powered by the shared name attribute.
+  </cs-details>
+
+  <cs-details name="group-1" summary="Section 3">
+    And here's the third section. You can have as many sections as you need — just make sure they all share the same
+    name and only one will be open at a time.
+  </cs-details>
+</div>
+```
+
+## 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/details/details.js';
+```
+
+**Self-Hosted**
+
+```js
+import './cornerstone/components/details/details.js';
+```
+
+**React**
+
+```js
+import CsDetails from '@cruglobal/cornerstone-components/react/details/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):
+
+- `(default)` — The details' main content.
+- `collapse-icon` — Optional collapse icon to use instead of the default. Works best with `<cs-icon>`.
+- `expand-icon` — Optional expand icon to use instead of the default. Works best with `<cs-icon>`.
+- `summary` — The details' summary. Alternatively, you can use the `summary` attribute.
+
+### Attributes & Properties
+
+| Property | Attribute | Description | Type | Default | Reflects |
+| --- | --- | --- | --- | --- | --- |
+| `appearance` | `appearance` | The element's visual appearance. | `'filled' \| 'outlined' \| 'filled-outlined' \| 'plain'` | `'outlined'` | Yes |
+| `disabled` | `disabled` | Disables the details so it can't be toggled. | `boolean` | `false` | Yes |
+| `iconPlacement` | `icon-placement` | The location of the expand/collapse icon. | `'start' \| 'end'` | `'end'` | Yes |
+| `name` | `name` | Groups related details elements. When one opens, others with the same name will close. | `string` | — | Yes |
+| `open` | `open` | Indicates whether or not the details is open. You can toggle this attribute to show and hide the details, or you can use the `show()` and `hide()` methods and this attribute will reflect the details' open state. | `boolean` | `false` | Yes |
+| `summary` | `summary` | The summary to show in the header. If you need to display HTML, use the `summary` slot instead. | `string` | — | — |
+
+### Methods
+
+| Name | Description | Arguments |
+| --- | --- | --- |
+| `hide()` | Hides the details | — |
+| `show()` | Shows the details. | — |
+
+### Events
+
+| Name | Description |
+| --- | --- |
+| `cs-after-hide` | Emitted after the details closes and all animations are complete. |
+| `cs-after-show` | Emitted after the details opens and all animations are complete. |
+| `cs-hide` | Emitted when the details closes. |
+| `cs-show` | Emitted when the details opens. |
+
+### CSS Custom Properties
+
+| Name | Description | Default |
+| --- | --- | --- |
+| `--hide-duration` | The hide duration to use when applying built-in animation classes. | `var(--cs-transition-normal)` |
+| `--show-duration` | The show duration to use when applying built-in animation classes. | `var(--cs-transition-normal)` |
+| `--spacing` | The amount of space around and between the details' content. Expects a single value. | — |
+
+### Custom States
+
+| Name | Description | CSS selector |
+| --- | --- | --- |
+| `animating` | Applied when the details is animating expand/collapse. | `:state(animating)` |
+
+### CSS Parts
+
+| Name | Description | CSS selector |
+| --- | --- | --- |
+| `content` | The details content. | `::part(content)` |
+| `details` | The component's outer wrapper. Styles you apply to the component are automatically applied to this part, so you usually don't need to deal with it unless you need to set the `display` property. | `::part(details)` |
+| `header` | The header that wraps both the summary and the expand/collapse icon. | `::part(header)` |
+| `icon` | The container that wraps the expand/collapse icons. | `::part(icon)` |
+| `summary` | The container that wraps the summary. | `::part(summary)` |
+
+### Dependencies
+
+- `<cs-icon>`