@warp-ds/elements 2.10.0-next.2 → 2.10.0-next.21

package/dist/docs/checkbox/checkbox.md

@@ -0,0 +1,356 @@
+# Checkbox (w-checkbox)
+
+## Description
+
+Checkbox lets users select one or more options. Use it for independent yes/no choices, multi-select lists, and terms or consent confirmations.
+
+# Checkbox Styling
+
+The checkbox component provides a comprehensive styling API through CSS custom properties (tokens).
+
+## Styling API
+
+### Label Tokens
+
+Customize the appearance of the label text:
+
+```css
+--w-c-checkbox-label-font-size: var(--w-font-size-m);
+--w-c-checkbox-label-line-height: var(--w-line-height-m);
+```
+
+### Control Tokens
+
+Customize the checkbox control (the box itself):
+
+```css
+--w-c-checkbox-control-size: 2rem;
+--w-c-checkbox-gap: 8px;
+--w-c-checkbox-radius: 4px;
+--w-c-checkbox-border-width: 1px;
+```
+
+### Color Tokens - Default State
+
+```css
+--w-c-checkbox-bg: var(--w-s-color-background);
+--w-c-checkbox-border-color: var(--w-s-color-border-strong);
+--w-c-checkbox-icon-color: var(--w-s-color-icon-inverted);
+```
+
+### Color Tokens - Checked State
+
+```css
+--w-c-checkbox-bg-checked: var(--w-s-color-background-primary);
+--w-c-checkbox-border-color-checked: var(--w-s-color-border-primary);
+--w-c-checkbox-checked-icon: var(--w-icon-toggle-checked);
+```
+
+### Color Tokens - Invalid State
+
+```css
+--w-c-checkbox-border-color-invalid: var(--w-s-color-border-negative);
+--w-c-checkbox-bg-invalid-checked: var(--w-s-color-background-negative);
+```
+
+### Color Tokens - Disabled State
+
+```css
+--w-c-checkbox-bg-disabled: var(--w-s-color-background-disabled-subtle);
+--w-c-checkbox-border-color-disabled: var(--w-s-color-border-disabled);
+--w-c-checkbox-bg-disabled-checked: var(--w-s-color-background-disabled);
+```
+
+### Focus Tokens
+
+```css
+--w-c-checkbox-outline-width: 2px;
+--w-c-checkbox-outline-color: var(--w-s-color-border-focus);
+--w-c-checkbox-outline-offset: var(--w-outline-offset, 1px);
+```
+
+### Animation Tokens
+
+```css
+--w-c-checkbox-transition: all 150ms cubic-bezier(0.4, 0, 0.2, 1);
+```
+
+## Parts
+
+For advanced styling needs beyond tokens, you can target internal elements using CSS parts:
+
+- `::part(base)` - The wrapper `<label>` element
+- `::part(control)` - The visual checkbox control (the box)
+- `::part(input)` - The native `<input type="checkbox">` element
+- `::part(label)` - The label content wrapper
+
+```css
+w-checkbox::part(control) {
+  /* Custom styling for the checkbox box */
+  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+}
+
+w-checkbox::part(label) {
+  /* Custom styling for label text */
+  text-transform: uppercase;
+}
+```
+
+## Example Usage
+
+### Customizing Size
+
+```css
+w-checkbox {
+  --w-c-checkbox-control-size: 2.4rem;
+  --w-c-checkbox-gap: 12px;
+}
+```
+
+### Customizing Colors
+
+```css
+w-checkbox {
+  --w-c-checkbox-bg-checked: var(--w-s-color-background-success);
+  --w-c-checkbox-border-color-checked: var(--w-s-color-border-success);
+}
+```
+
+### Customizing Border Radius
+
+```css
+w-checkbox {
+  --w-c-checkbox-radius: 8px; /* More rounded */
+}
+
+/* Or fully rounded */
+w-checkbox {
+  --w-c-checkbox-radius: 50%;
+}
+```
+
+### Customizing Focus Outline
+
+```css
+w-checkbox {
+  --w-c-checkbox-outline-width: 3px;
+  --w-c-checkbox-outline-color: var(--w-s-color-border-info);
+  --w-c-checkbox-outline-offset: 2px;
+}
+```
+
+### Disabling Transitions
+
+```css
+w-checkbox {
+  --w-c-checkbox-transition: none;
+}
+```
+
+### Using Parts for Advanced Styling
+
+```css
+/* Add a subtle shadow to the checkbox */
+w-checkbox::part(control) {
+  box-shadow: inset 0 1px 3px rgba(0,0,0,0.1);
+}
+
+/* Style the label with custom spacing */
+w-checkbox::part(label) {
+  padding-left: 4px;
+  font-weight: 500;
+}
+```
+
+## Label Content
+
+Unlike textfield/textarea components, checkbox labels accept rich HTML content via the default slot:
+
+```html
+<w-checkbox>
+  I agree to the <a href="/terms">terms and conditions</a>
+</w-checkbox>
+
+<w-checkbox>
+  <strong>Important:</strong> Check this box
+</w-checkbox>
+```
+
+Style the label content directly or use `::part(label)` to target the wrapper.
+
+### `<w-checkbox>` API
+
+#### Properties
+
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| _computedInvalid (JS only) | `boolean` | `-` | Computed invalid state: combines own invalid with group invalid |
+| blur (JS only) | `blur() => void` | `-` | - |
+| checkValidity (JS only) | `checkValidity() => boolean` | `-` | Checks whether the checkbox passes constraint validation |
+| checked | `boolean` | `false` | Whether the checkbox is checked. |
+| click (JS only) | `click() => void` | `-` | - |
+| disabled | `boolean` | `false` | Whether the checkbox is disabled. |
+| focus (JS only) | `focus(options?: FocusOptions) => void` | `-` | - |
+| indeterminate | `boolean` | `false` | Whether the checkbox is visually indeterminate. |
+| input (JS only) | `HTMLInputElement` | `-` | - |
+| invalid | `boolean` | `false` | Whether the checkbox is visually invalid. |
+| name | `string \| undefined` | `-` | The name of the checkbox. |
+| reportValidity (JS only) | `reportValidity() => boolean` | `-` | Checks validity and shows the browser's validation message if invalid |
+| required | `boolean` | `false` | Whether the checkbox must be checked before form submission. |
+| resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
+| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
+| validationMessage (JS only) | `string` | `-` | Returns the validation message if the checkbox is invalid, otherwise an empty string |
+| validity (JS only) | `ValidityState` | `-` | Returns the validity state of the checkbox |
+| value | `string \| null` | `null` | The value submitted when the checkbox is checked. |
+
+#### Property Details
+
+##### _computedInvalid (JS only)
+
+Computed invalid state: combines own invalid with group invalid
+
+- Type: `boolean`
+- Default: `-`
+
+##### blur (JS only)
+
+
+
+- Type: `blur() => void`
+- Default: `-`
+
+##### checkValidity (JS only)
+
+Checks whether the checkbox passes constraint validation
+
+- Type: `checkValidity() => boolean`
+- Default: `-`
+
+##### checked
+
+Whether the checkbox is checked.
+
+Checked checkboxes submit their value with form data. The property is reflected to the `checked` attribute.
+
+- Type: `boolean`
+- Default: `false`
+
+##### click (JS only)
+
+
+
+- Type: `click() => void`
+- Default: `-`
+
+##### disabled
+
+Whether the checkbox is disabled.
+
+Disabled checkboxes cannot be focused, changed, or submitted with form data.
+
+- Type: `boolean`
+- Default: `false`
+
+##### focus (JS only)
+
+
+
+- Type: `focus(options?: FocusOptions) => void`
+- Default: `-`
+
+##### indeterminate
+
+Whether the checkbox is visually indeterminate.
+
+Use this for parent options that represent a mixed set of child selections. Clicking the checkbox clears the indeterminate state and sets the checkbox to checked.
+
+- Type: `boolean`
+- Default: `false`
+
+##### input (JS only)
+
+
+
+- Type: `HTMLInputElement`
+- Default: `-`
+
+##### invalid
+
+Whether the checkbox is visually invalid.
+
+Use this to show an externally managed validation error. Required validation also sets the invalid state after the user interacts with the checkbox or tries to submit the form.
+
+- Type: `boolean`
+- Default: `false`
+
+##### name
+
+The name of the checkbox.
+
+When the checkbox is checked and belongs to a form, this name is submitted with the checkbox value. If the checkbox is inside a `w-checkbox-group` with a name, the group name is used when the checkbox does not have its own name.
+
+- Type: `string | undefined`
+- Default: `-`
+
+##### reportValidity (JS only)
+
+Checks validity and shows the browser's validation message if invalid
+
+- Type: `reportValidity() => boolean`
+- Default: `-`
+
+##### required
+
+Whether the checkbox must be checked before form submission.
+
+A required checkbox is invalid until it is checked. For requiring at least one option in a set, use `required` on `w-checkbox-group`.
+
+- Type: `boolean`
+- Default: `false`
+
+##### resetFormControl (JS only)
+
+
+
+- Type: `resetFormControl() => void`
+- Default: `-`
+
+##### shadowRootOptions (JS only)
+
+
+
+- Type: `object`
+- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
+
+##### validationMessage (JS only)
+
+Returns the validation message if the checkbox is invalid, otherwise an empty string
+
+- Type: `string`
+- Default: `-`
+
+##### validity (JS only)
+
+Returns the validity state of the checkbox
+
+- Type: `ValidityState`
+- Default: `-`
+
+##### value
+
+The value submitted when the checkbox is checked.
+
+If no value attribute is set, the checkbox defaults to `on`. Unchecked and disabled checkboxes do not submit a value.
+
+- Type: `string | null`
+- Default: `null`
+
+#### Events
+
+##### change
+
+
+
+- Type: `Event`
+
+

package/dist/docs/checkbox/styling.md

@@ -0,0 +1,173 @@
+# Checkbox Styling
+
+The checkbox component provides a comprehensive styling API through CSS custom properties (tokens).
+
+## Styling API
+
+### Label Tokens
+
+Customize the appearance of the label text:
+
+```css
+--w-c-checkbox-label-font-size: var(--w-font-size-m);
+--w-c-checkbox-label-line-height: var(--w-line-height-m);
+```
+
+### Control Tokens
+
+Customize the checkbox control (the box itself):
+
+```css
+--w-c-checkbox-control-size: 2rem;
+--w-c-checkbox-gap: 8px;
+--w-c-checkbox-radius: 4px;
+--w-c-checkbox-border-width: 1px;
+```
+
+### Color Tokens - Default State
+
+```css
+--w-c-checkbox-bg: var(--w-s-color-background);
+--w-c-checkbox-border-color: var(--w-s-color-border-strong);
+--w-c-checkbox-icon-color: var(--w-s-color-icon-inverted);
+```
+
+### Color Tokens - Checked State
+
+```css
+--w-c-checkbox-bg-checked: var(--w-s-color-background-primary);
+--w-c-checkbox-border-color-checked: var(--w-s-color-border-primary);
+--w-c-checkbox-checked-icon: var(--w-icon-toggle-checked);
+```
+
+### Color Tokens - Invalid State
+
+```css
+--w-c-checkbox-border-color-invalid: var(--w-s-color-border-negative);
+--w-c-checkbox-bg-invalid-checked: var(--w-s-color-background-negative);
+```
+
+### Color Tokens - Disabled State
+
+```css
+--w-c-checkbox-bg-disabled: var(--w-s-color-background-disabled-subtle);
+--w-c-checkbox-border-color-disabled: var(--w-s-color-border-disabled);
+--w-c-checkbox-bg-disabled-checked: var(--w-s-color-background-disabled);
+```
+
+### Focus Tokens
+
+```css
+--w-c-checkbox-outline-width: 2px;
+--w-c-checkbox-outline-color: var(--w-s-color-border-focus);
+--w-c-checkbox-outline-offset: var(--w-outline-offset, 1px);
+```
+
+### Animation Tokens
+
+```css
+--w-c-checkbox-transition: all 150ms cubic-bezier(0.4, 0, 0.2, 1);
+```
+
+## Parts
+
+For advanced styling needs beyond tokens, you can target internal elements using CSS parts:
+
+- `::part(base)` - The wrapper `<label>` element
+- `::part(control)` - The visual checkbox control (the box)
+- `::part(input)` - The native `<input type="checkbox">` element
+- `::part(label)` - The label content wrapper
+
+```css
+w-checkbox::part(control) {
+  /* Custom styling for the checkbox box */
+  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+}
+
+w-checkbox::part(label) {
+  /* Custom styling for label text */
+  text-transform: uppercase;
+}
+```
+
+## Example Usage
+
+### Customizing Size
+
+```css
+w-checkbox {
+  --w-c-checkbox-control-size: 2.4rem;
+  --w-c-checkbox-gap: 12px;
+}
+```
+
+### Customizing Colors
+
+```css
+w-checkbox {
+  --w-c-checkbox-bg-checked: var(--w-s-color-background-success);
+  --w-c-checkbox-border-color-checked: var(--w-s-color-border-success);
+}
+```
+
+### Customizing Border Radius
+
+```css
+w-checkbox {
+  --w-c-checkbox-radius: 8px; /* More rounded */
+}
+
+/* Or fully rounded */
+w-checkbox {
+  --w-c-checkbox-radius: 50%;
+}
+```
+
+### Customizing Focus Outline
+
+```css
+w-checkbox {
+  --w-c-checkbox-outline-width: 3px;
+  --w-c-checkbox-outline-color: var(--w-s-color-border-info);
+  --w-c-checkbox-outline-offset: 2px;
+}
+```
+
+### Disabling Transitions
+
+```css
+w-checkbox {
+  --w-c-checkbox-transition: none;
+}
+```
+
+### Using Parts for Advanced Styling
+
+```css
+/* Add a subtle shadow to the checkbox */
+w-checkbox::part(control) {
+  box-shadow: inset 0 1px 3px rgba(0,0,0,0.1);
+}
+
+/* Style the label with custom spacing */
+w-checkbox::part(label) {
+  padding-left: 4px;
+  font-weight: 500;
+}
+```
+
+## Label Content
+
+Unlike textfield/textarea components, checkbox labels accept rich HTML content via the default slot:
+
+```html
+<w-checkbox>
+  I agree to the <a href="/terms">terms and conditions</a>
+</w-checkbox>
+
+<w-checkbox>
+  <strong>Important:</strong> Check this box
+</w-checkbox>
+```
+
+Style the label content directly or use `::part(label)` to target the wrapper.

package/dist/docs/checkbox-group/accessibility.md

@@ -0,0 +1,71 @@
+## Accessibility
+
+Checkbox group renders the child checkboxes inside an element with `role="group"`. The group label is connected to the group, and help text is connected when provided.
+
+### Provide A Group Label
+
+Use `label` to describe the shared question or topic.
+
+```html
+<w-checkbox-group label="Interests" name="interests">
+  <w-checkbox value="housing">Housing</w-checkbox>
+  <w-checkbox value="jobs">Jobs</w-checkbox>
+  <w-checkbox value="travel">Travel</w-checkbox>
+</w-checkbox-group>
+```
+
+The group label should not duplicate every option label. It should explain what the options are about.
+
+### Use Help Text For Extra Context
+
+Use `help-text` for instructions, constraints, or validation feedback.
+
+```html
+<w-checkbox-group label="Interests" help-text="Select all that apply" name="interests">
+  <w-checkbox value="housing">Housing</w-checkbox>
+  <w-checkbox value="jobs">Jobs</w-checkbox>
+  <w-checkbox value="travel">Travel</w-checkbox>
+</w-checkbox-group>
+```
+
+Keep help text short and actionable.
+
+### Required Groups
+
+Use `required` on the group when at least one option must be selected.
+
+```html
+<w-checkbox-group label="Preferences" required help-text="Choose at least one" name="preferences">
+  <w-checkbox value="email">Email</w-checkbox>
+  <w-checkbox value="sms">SMS</w-checkbox>
+</w-checkbox-group>
+```
+
+Do not put `required` on each child checkbox for a "choose at least one" requirement. That would mean every option must be selected.
+
+### Validation Feedback
+
+Do not rely on invalid styling alone. Provide clear help text that explains what the user needs to do.
+
+```html
+<w-checkbox-group label="Preferences" invalid help-text="Select at least one option" name="preferences">
+  <w-checkbox value="email">Email</w-checkbox>
+  <w-checkbox value="sms">SMS</w-checkbox>
+</w-checkbox-group>
+```
+
+When the group is invalid, the invalid state is also shared with child checkboxes for consistent styling and accessibility state.
+
+### Checkbox Labels
+
+Each child checkbox still needs its own clear label.
+
+```html
+<w-checkbox-group label="Contact preferences" name="contact">
+  <w-checkbox value="email">Email</w-checkbox>
+  <w-checkbox value="sms">SMS</w-checkbox>
+  <w-checkbox value="push">Push notifications</w-checkbox>
+</w-checkbox-group>
+```
+
+Avoid option labels that only make sense visually, such as "Yes" or "This one", unless the group label gives enough context.

package/dist/docs/checkbox-group/api.md

@@ -0,0 +1,103 @@
+## `<w-checkbox-group>` API
+
+Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
+
+### Properties
+
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| checkValidity (JS only) | `checkValidity() => boolean` | `-` | Checks whether the group passes constraint validation |
+| focus (JS only) | `focus(options?: FocusOptions) => void` | `-` | Sets focus on the checkbox group. |
+| help-text | `string \| undefined` | `-` | Help text displayed below the checkbox group. |
+| invalid | `boolean` | `false` | Whether the checkbox group is visually invalid. |
+| label | `string \| undefined` | `-` | The group label displayed above the checkboxes. |
+| name | `string \| undefined` | `-` | The name applied to child checkboxes when they do not provide one. |
+| optional | `boolean` | `false` | Whether to show optional text next to the label. |
+| reportValidity (JS only) | `reportValidity() => boolean` | `-` | Checks validity and shows the validation message if invalid |
+| required | `boolean` | `false` | Whether at least one checkbox in the group must be selected. |
+| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
+
+### Property Details
+
+#### checkValidity (JS only)
+
+Checks whether the group passes constraint validation
+
+- Type: `checkValidity() => boolean`
+- Default: `-`
+
+#### focus (JS only)
+
+Sets focus on the checkbox group.
+
+- Type: `focus(options?: FocusOptions) => void`
+- Default: `-`
+
+#### help-text
+
+Help text displayed below the checkbox group.
+
+Use this for supporting guidance or validation feedback. When required validation fails, the group replaces this text with the localized required message.
+
+- Type: `string | undefined`
+- Default: `-`
+
+#### invalid
+
+Whether the checkbox group is visually invalid.
+
+Use this to show an externally managed validation error for the group. The invalid state is also shared with child checkboxes for consistent styling and accessibility state.
+
+- Type: `boolean`
+- Default: `false`
+
+#### label
+
+The group label displayed above the checkboxes.
+
+Use this to describe the shared question or topic for the checkbox options. The label is connected to the internal group for assistive technologies.
+
+- Type: `string | undefined`
+- Default: `-`
+
+#### name
+
+The name applied to child checkboxes when they do not provide one.
+
+Use this when the grouped checkboxes should submit values under the same form field name. Individual checkboxes can still override the group name with their own `name`.
+
+- Type: `string | undefined`
+- Default: `-`
+
+#### optional
+
+Whether to show optional text next to the label.
+
+Use this to indicate that selecting an option from the group is not required.
+
+- Type: `boolean`
+- Default: `false`
+
+#### reportValidity (JS only)
+
+Checks validity and shows the validation message if invalid
+
+- Type: `reportValidity() => boolean`
+- Default: `-`
+
+#### required
+
+Whether at least one checkbox in the group must be selected.
+
+Required validation is managed by the group. The individual checkboxes provide the submitted form values.
+
+- Type: `boolean`
+- Default: `false`
+
+#### shadowRootOptions (JS only)
+
+
+
+- Type: `object`
+- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
+