@warp-ds/elements 2.10.0-next.9 → 2.10.0

package/dist/docs/checkbox/checkbox.md

@@ -4,6 +4,180 @@
 
 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
@@ -11,14 +185,20 @@ Checkbox lets users select one or more options. Use it for independent yes/no ch
 | 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 \| null` | `-` | - |
+| 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. |
-| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true }` | - |
+| 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. |
@@ -32,6 +212,20 @@ 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.
@@ -41,6 +235,13 @@ Checked checkboxes submit their value with form data. The property is reflected
 - Type: `boolean`
 - Default: `false`
 
+##### click (JS only)
+
+
+
+- Type: `click() => void`
+- Default: `-`
+
 ##### disabled
 
 Whether the checkbox is disabled.
@@ -50,6 +251,13 @@ 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.
@@ -63,7 +271,7 @@ Use this for parent options that represent a mixed set of child selections. Clic
 
 
 
-- Type: `HTMLInputElement | null`
+- Type: `HTMLInputElement`
 - Default: `-`
 
 ##### invalid
@@ -84,6 +292,13 @@ When the checkbox is checked and belongs to a form, this name is submitted with
 - 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.
@@ -93,12 +308,19 @@ A required checkbox is invalid until it is checked. For requiring at least one o
 - Type: `boolean`
 - Default: `false`
 
+##### resetFormControl (JS only)
+
+
+
+- Type: `resetFormControl() => void`
+- Default: `-`
+
 ##### shadowRootOptions (JS only)
 
 
 
 - Type: `object`
-- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true }`
+- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
 
 ##### validationMessage (JS only)
 

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/api.md

@@ -6,23 +6,40 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| help-text | `string` | `-` | Help text displayed below the checkbox group. |
+| 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` | `-` | The group label displayed above the checkboxes. |
-| name | `string` | `-` | The name applied to child checkboxes when they do not provide one. |
+| 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`
+- Type: `string | undefined`
 - Default: `-`
 
 #### invalid
@@ -40,7 +57,7 @@ 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`
+- Type: `string | undefined`
 - Default: `-`
 
 #### name
@@ -49,7 +66,7 @@ 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`
+- Type: `string | undefined`
 - Default: `-`
 
 #### optional
@@ -61,6 +78,13 @@ 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.