@mcp-b/web-components 0.2.0

package/dist/radio-CieMa4zU.d.ts

@@ -0,0 +1,460 @@
+import { t as SigveloRadioItem } from "./radio-item-Xq2U3cMu.js";
+import { CSSResultGroup, PropertyValues } from "lit";
+import { SigveloFormControlElement } from "@mcp-b/wc-support/base/sigvelo-element";
+
+//#region src/components/radio/radio.d.ts
+/**
+ * <sigvelo-radio>
+ *
+ * @summary Allows the user to select one option from a group of choices.
+ * @tag sigvelo-radio
+ * @documentation https://design-system.sigvelo.com/docs/components/radio
+ * @status stable
+ * @since 1.0
+ *
+ * @dependency sigvelo-radio-item
+ *
+ * @slot - The radio items to place in the group.
+ * @slot label - The radio's label. For plain-text labels, you can use the `label` attribute instead.
+ * @slot description - The radios's description. For plain-text descriptions, you can use the `description`
+ *  attribute instead.
+ *
+ * @event sigvelo-change - Emitted when the user commits changes to the radio's value.
+ * @event sigvelo-input - Emitted when the radio receives input.
+ *
+ * @csspart label - The element that contains the radio's label.
+ * @csspart description - The element that contains the radio's description.
+ * @csspart group - The element that wraps the grouped radios.
+ *
+ * @cssstate user-valid - Applied when the radio is valid and the user has sufficiently interacted with it.
+ * @cssstate user-invalid - Applied when the radio is invalid and the user has sufficiently interacted with it.
+ *
+ * @example Default
+ * Radios follow the ARIA APG radio group pattern for accessibility. Unlike native radio buttons, Sigvelo radio items must be placed inside a radio controller as shown below.
+ *
+ * ```html
+ * <sigvelo-radio
+ *   label="Color"
+ *   description="Select a color for your new cat"
+ *   name="color"
+ *   value="black"
+ * >
+ *   <sigvelo-radio-item value="black">Black</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="white">White</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="orange">Orange</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="gray">Gray</sigvelo-radio-item>
+ * </sigvelo-radio>
+ * ```
+ *
+ * @example Labels and descriptions
+ * You can use the `label` and `description` attributes to provide plain text labels and descriptions for the radio. If you want to provide HTML, use the `label` and `description` slots instead.
+ *
+ * ```html
+ * <sigvelo-radio label="Favorite pet" name="animal">
+ *   <span slot="description">
+ *     For more information, <a href="https://example.com/" target="_blank">visit our website</a>.
+ *   </span>
+ *   <sigvelo-radio-item value="cat">Cat</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="dog">Dog</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="bird">Bird</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="lizard">Lizard</sigvelo-radio-item>
+ * </sigvelo-radio>
+ * ```
+ *
+ * @example Providing an initial value
+ * Use the `value` attribute to provide an initial value for the radio. The value should match an existing radio item's value.
+ *
+ * ```html
+ * <sigvelo-radio label="Fur type" name="fur" value="short">
+ *   <sigvelo-radio-item value="short">Short</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="medium">Medium</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="long">Long</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="hairless">Hairless</sigvelo-radio-item>
+ * </sigvelo-radio>
+ * ```
+ *
+ * **Warning:** This behavior is different from native radios that use the `checked` attribute to set the value. With `<sigvelo-radio>`, always use the `value` attribute to set the value.
+ *
+ * @example Changing the orientation
+ * To stack radio items on top of each other instead of side by side, set the `orientation` attribute to `vertical`.
+ *
+ * ```html
+ * <sigvelo-radio orientation="vertical" label="Fur type" name="fur">
+ *   <sigvelo-radio-item value="short">Short</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="medium">Medium</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="long">Long</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="hairless">Hairless</sigvelo-radio-item>
+ * </sigvelo-radio>
+ * ```
+ *
+ * @example Filled radios
+ * Set the `variant` attribute to `filled` to change a radio item's variant.
+ *
+ * ```html
+ * <sigvelo-radio label="Favorite pet" name="animal">
+ *   <sigvelo-radio-item variant="filled" value="cat">Cat</sigvelo-radio-item>
+ *   <sigvelo-radio-item variant="filled" value="dog">Dog</sigvelo-radio-item>
+ *   <sigvelo-radio-item variant="filled" value="bird">Bird</sigvelo-radio-item>
+ *   <sigvelo-radio-item variant="filled" value="lizard">Lizard</sigvelo-radio-item>
+ * </sigvelo-radio>
+ * ```
+ *
+ * @example Changing the size
+ * Use the `size` attribute to change a radio item's size.
+ *
+ * ```html
+ * <sigvelo-radio label="Select a size" name="size" orientation="vertical">
+ *   <sigvelo-radio-item size="xs" value="a">Extra small</sigvelo-radio-item>
+ *   <sigvelo-radio-item size="sm" value="b">Small</sigvelo-radio-item>
+ *   <sigvelo-radio-item size="md" value="c">Medium</sigvelo-radio-item>
+ *   <sigvelo-radio-item size="lg" value="d">Large</sigvelo-radio-item>
+ *   <sigvelo-radio-item size="xl" value="e">Extra large</sigvelo-radio-item>
+ * </sigvelo-radio>
+ * ```
+ *
+ * @example Disabling
+ * To disable the entire control, add the `disabled` attribute to the radio element.
+ *
+ * ```html
+ * <sigvelo-radio label="Favorite pet" name="animal" disabled value="cat">
+ *   <sigvelo-radio-item value="cat">Cat</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="dog">Dog</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="bird">Bird</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="lizard">Lizard</sigvelo-radio-item>
+ * </sigvelo-radio>
+ * ```
+ *
+ * To disable individual options, add the `disabled` attribute to one or more radio items.
+ *
+ * ```html
+ * <sigvelo-radio label="Favorite pet" name="animal" value="cat">
+ *   <sigvelo-radio-item value="cat">Cat</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="dog" disabled>Dog</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="bird" disabled>Bird</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="lizard">Lizard</sigvelo-radio-item>
+ * </sigvelo-radio>
+ * ```
+ *
+ * @example Validation
+ * The `required` attribute can be applied to enable validation using the Constraint Validation API. This will prevent form submission until a radio item is checked.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank">
+ *   <sigvelo-radio label="Select one" name="animal" required>
+ *     <sigvelo-radio-item value="cats">Cats</sigvelo-radio-item>
+ *     <sigvelo-radio-item value="dogs">Dogs</sigvelo-radio-item>
+ *   </sigvelo-radio>
+ *   <br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ * ```
+ *
+ * @example Using custom validation
+ * Use the `setCustomValidity()` method to make the radio invalid and show a custom error message on submit. This will override all other validation parameters. To clear the error, remove the attribute or set it to an empty string.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank" id="radio__custom-validation">
+ *   <sigvelo-radio label="Select one" name="animal">
+ *     <sigvelo-radio-item value="cats">Cats</sigvelo-radio-item>
+ *     <sigvelo-radio-item value="dogs">Dogs</sigvelo-radio-item>
+ *   </sigvelo-radio>
+ *   <br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ *
+ * <script type="module">
+ *   import { allDefined } from '/dist/sigvelo.js';
+ *
+ *   await allDefined();
+ *
+ *   const form = document.getElementById('radio__custom-validation');
+ *   const radio = form.querySelector('sigvelo-radio');
+ *
+ *   radio.setCustomValidity('Not so fast, bubba!');
+ * </script>
+ * ```
+ *
+ * @example Styling validation
+ * You can style valid and invalid radios using the `:valid` and `:invalid` pseudo classes.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank" class="radio__validation-pseudo">
+ *   <sigvelo-radio label="Select one" name="animal" required>
+ *     <sigvelo-radio-item value="cats">Cats</sigvelo-radio-item>
+ *     <sigvelo-radio-item value="dogs">Dogs</sigvelo-radio-item>
+ *   </sigvelo-radio>
+ *   <br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ *
+ * <style>
+ *   .radio__validation-pseudo {
+ *     sigvelo-radio:valid {
+ *       outline: solid 2px var(--sigvelo-color-success-border);
+ *       outline-offset: .5rem;
+ *     }
+ *
+ *     sigvelo-radio:invalid {
+ *       outline: solid 2px var(--sigvelo-color-danger-border);
+ *       outline-offset: .5rem;
+ *     }
+ *   }
+ * </style>
+ * ```
+ *
+ * However, these selectors will match even before the user has had a chance to fill out the form. More often than not, you'll want to use the `user-valid` and `user-invalid` custom states instead. This way, validation styles are only shown _after_ the user interacts with the form control or when the form is submitted.
+ *
+ * ```html
+ * <form action="about:blank" method="get" target="_blank" class="radio__validation-custom">
+ *   <sigvelo-radio label="Select one" name="animal" required>
+ *     <sigvelo-radio-item value="cats">Cats</sigvelo-radio-item>
+ *     <sigvelo-radio-item value="dogs">Dogs</sigvelo-radio-item>
+ *   </sigvelo-radio>
+ *   <br>
+ *   <sigvelo-button type="submit" color="primary">Submit</sigvelo-button>
+ *   <sigvelo-button type="reset">Reset</sigvelo-button>
+ * </form>
+ *
+ * <style>
+ *   .radio__validation-custom {
+ *     sigvelo-radio:state(user-valid) {
+ *       outline: solid 2px var(--sigvelo-color-success-border);
+ *       outline-offset: .5rem;
+ *     }
+ *
+ *     sigvelo-radio:state(user-invalid) {
+ *       outline: solid 2px var(--sigvelo-color-danger-border);
+ *       outline-offset: .5rem;
+ *     }
+ *   }
+ * </style>
+ * ```
+ *
+ * @example Styling radios
+ * Radios come with a simple, minimal appearance. Feel free to customize them with your own styles. Here are some examples, for inspiration.
+ *
+ * ```html
+ * <sigvelo-radio label="How would you like to login?" name="auth" class="radio__auth">
+ *   <sigvelo-radio-item value="magic">
+ *     <sigvelo-icon name="wand"></sigvelo-icon> Magic link
+ *   </sigvelo-radio-item>
+ *   <sigvelo-radio-item value="password">
+ *     <sigvelo-icon name="password"></sigvelo-icon> Password
+ *   </sigvelo-radio-item>
+ * </sigvelo-radio>
+ *
+ * <style>
+ *   .radio__auth {
+ *     sigvelo-radio-item {
+ *       background: var(--sigvelo-color-surface);
+ *       border: solid 1px var(--sigvelo-color-neutral-border-muted);
+ *       border-radius: .5rem;
+ *       box-shadow: var(--sigvelo-elevation-hairline);
+ *       padding: 1rem;
+ *       cursor: pointer;
+ *     }
+ *
+ *     sigvelo-radio-item:state(checked) {
+ *       background-color: var(--sigvelo-color-primary-bg-subtle);
+ *       border-color: var(--sigvelo-color-primary-border-muted);
+ *     }
+ *
+ *     sigvelo-radio-item:focus-visible {
+ *       outline: var(--sigvelo-focus-ring);
+ *       outline-offset: var(--sigvelo-focus-offset);
+ *     }
+ *   }
+ * </style>
+ * ```
+ *
+ * ```html
+ * <sigvelo-radio
+ *   label="Select a plan"
+ *   description="All plans come with a free cat"
+ *   name="plan"
+ *   class="radio__hosting"
+ * >
+ *   <sigvelo-radio-item value="startup">
+ *     Startup<br>
+ *     <small>12GB &middot; 6 CPUs &middot; 256GB SSD</small>
+ *   </sigvelo-radio-item>
+ *
+ *   <sigvelo-radio-item value="business">
+ *     Business<br>
+ *     <small>16GB &middot; 8 CPUs &middot; 512GB SSD</small>
+ *   </sigvelo-radio-item>
+ *
+ *   <sigvelo-radio-item value="enterprise">
+ *     Enterprise<br>
+ *     <small>32GB &middot; 12 CPUs &middot; 1TB SSD</small>
+ *   </sigvelo-radio-item>
+ * </sigvelo-radio>
+ *
+ * <style>
+ *   .radio__hosting {
+ *     sigvelo-radio-item {
+ *       position: relative;
+ *       width: 100%;
+ *       background: var(--sigvelo-color-surface);
+ *       border: solid 1px var(--sigvelo-color-neutral-border-muted);
+ *       box-shadow: var(--sigvelo-elevation-hairline);
+ *       border-radius: .5rem;
+ *       padding: 1rem;
+ *     }
+ *
+ *     sigvelo-radio-item::part(label) {
+ *       width: 100%;
+ *       display: block;
+ *     }
+ *
+ *     sigvelo-radio-item::part(visual-box) {
+ *       position: absolute;
+ *       top: calc(50% - .625rem);
+ *       right: 1rem;
+ *     }
+ *
+ *     sigvelo-radio-item:state(checked) {
+ *       background-color: var(--sigvelo-color-primary-bg-subtle);
+ *       border-color: var(--sigvelo-color-primary-border-muted);
+ *     }
+ *
+ *     sigvelo-radio-item:focus-visible {
+ *       outline: var(--sigvelo-focus-ring);
+ *       outline-offset: 2px;
+ *     }
+ *
+ *     small {
+ *       color: var(--sigvelo-color-text-muted);
+ *     }
+ *   }
+ * </style>
+ * ```
+ *
+ * ```html
+ * <sigvelo-radio
+ *   label="Color"
+ *   description="Choose a color for your new device"
+ *   name="color"
+ *   class="radio__colors"
+ * >
+ *   <sigvelo-radio-item value="silver" style="color: #b6b9c9;">Silver</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="blue" style="color: #83c0f5;">Blue</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="rose" style="color: #eea3bb;">Rose</sigvelo-radio-item>
+ *   <sigvelo-radio-item value="gold" style="color: #d1b86c;">Gold</sigvelo-radio-item>
+ * </sigvelo-radio>
+ *
+ * <style>
+ *   .radio__colors {
+ *     &::part(group) {
+ *       gap: .5rem;
+ *     }
+ *
+ *     sigvelo-radio-item {
+ *       width: 3rem;
+ *       height: 3rem;
+ *       background-color: currentColor;
+ *       background-image: linear-gradient(#fff8, transparent);
+ *       box-shadow: inset 0 1px 2px color-mix(in oklab, currentColor, black 12.5%);
+ *       border-radius: var(--sigvelo-radius-circle);
+ *       cursor: pointer;
+ *     }
+ *
+ *     sigvelo-radio-item:state(checked) {
+ *       outline: var(--sigvelo-border-style) var(--sigvelo-focus-width) currentColor;
+ *       outline-offset: 2px;
+ *     }
+ *
+ *     sigvelo-radio-item:focus-visible {
+ *       outline: var(--sigvelo-focus-ring);
+ *       outline-offset: 2px;
+ *     }
+ *
+ *     sigvelo-radio-item::part(label) {
+ *       position: absolute;
+ *       width: 1px;
+ *       height: 1px;
+ *       overflow: hidden;
+ *       white-space: nowrap;
+ *       clip-path: inset(50%);
+ *     }
+ *   }
+ * </style>
+ * ```
+ *
+ * **Warning:** It's not recommended to hide the radio button unless your styles make it very clear to users that the control is selectable.
+ */
+declare class SigveloRadio extends SigveloFormControlElement {
+  static formAssociated: boolean;
+  static observeSlots: boolean;
+  static styles: CSSResultGroup;
+  protected get focusableAnchor(): SigveloRadioItem;
+  group: HTMLElement;
+  isInvalid: boolean;
+  hadUserInteraction: boolean;
+  wasSubmitted: boolean;
+  /**
+   * The radio's label. If you need to provide HTML in the label, use the `label` slot instead.
+   */
+  label: string;
+  /**
+   * The radio's description. If you need to provide HTML in the description, use the `description` slot instead.
+   */
+  description: string;
+  /** The name of the radio. This will be submitted with the form as a name/value pair. */
+  name: string;
+  /** The radio's current value. Set this to change the selected item. */
+  value: string;
+  /** The orientation of grouped items. */
+  orientation: "horizontal" | "vertical";
+  /**
+   * The form to associate this control with. If omitted, the closest containing `<form>` will be used. The value of
+   * this attribute must be an ID of a form in the same document or shadow root.
+   */
+  form: string;
+  /** Indicates at least one option in the radio is required. */
+  required: boolean;
+  /** Disables the radio control. */
+  disabled: boolean;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  firstUpdated(): void;
+  updated(changedProperties: PropertyValues<this>): void;
+  /** @internal Called when a containing fieldset is disabled. */
+  formDisabledCallback(isDisabled: boolean): void;
+  /** @internal Called when the form is reset. */
+  formResetCallback(): void;
+  /** Gets an array of radio items slotted into the radio. */
+  private getItems;
+  private handleHostInvalid;
+  private handleGroupClick;
+  private handleGroupKeyDown;
+  /**
+   * @internal Makes only the selected radio item tabbable. If no radio item is selected, the first non-disabled radio
+   * item will be tabbable.
+   */
+  resetRovingTabIndex(): void;
+  /** Gets the selected item. */
+  private getSelectedItem;
+  /**
+   * Sets the selected item and updates the roving tab index. If `null` is provided, the selection will be cleared and
+   * the tab index will go to the first radio item.
+   */
+  private setSelectedItem;
+  /** Updates the controller disabled state for all radio items */
+  private updateControllerDisabledState;
+  /** Sets the form control's validity */
+  private updateValidity;
+  /** Sets focus to the selected item or the first item if none are selected. */
+  focus(options?: FocusOptions): void;
+  render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    "sigvelo-radio": SigveloRadio;
+  }
+}
+//#endregion
+export { SigveloRadio as t };