@mhmo91/schmancy 0.9.14 → 0.9.16

package/src/switch/switch.ts

@@ -5,12 +5,15 @@ import { customElement, property } from 'lit/decorators.js'
 export type SchmancySwitchChangeEvent = CustomEvent<{ value: boolean }>
 
 /**
- * Binary on/off control. Form-associated, keyboard-accessible, semantically a
- * switch (ARIA role="switch"). Distinct from `schmancy-checkbox`: a switch
- * represents an immediate state change, a checkbox represents a selection in
- * a form to be submitted.
+ * Binary on/off control with immediate effect. Form-associated, keyboard-accessible, semantically a switch (ARIA role="switch"). Distinct from `schmancy-checkbox`: a switch represents an immediate state change, a checkbox represents a selection in a form to be submitted.
  *
  * @element schmancy-switch
+ * @summary Use when flipping the control takes effect right away (e.g. "Dark mode", "Enable notifications"). Prefer schmancy-checkbox for form submissions.
+ * @example
+ * <schmancy-switch ?checked=${this.darkMode} @change=${(e) => this.darkMode = e.detail.value}>
+ *   Dark mode
+ * </schmancy-switch>
+ * @platform switch change - Accessible native `<button role="switch" aria-checked>` under the hood. No native HTML element exists; falls back to a styled checkbox if the tag never registers.
  * @fires change - `CustomEvent<{ value: boolean }>` when the state changes.
  * @attr checked - Initial checked state (also reflected via `value`).
  * @attr disabled - Disables interaction.

package/src/textarea/textarea.ts

@@ -8,7 +8,15 @@ import style from './textarea.scss?inline'
 import { TailwindElement } from '@mixins/index'
 
 /**
- * Textarea component with auto-resize and form integration.
+ * Multi-line text input with auto-resize and form integration. Form-associated.
+ *
+ * @element schmancy-textarea
+ * @summary Textarea for freeform text — notes, descriptions, messages. Auto-grows with content up to a maxlength.
+ * @example
+ * <schmancy-textarea name="description" label="Description" rows="4" maxlength="500"></schmancy-textarea>
+ * @platform textarea change - Schmancy-skinned native `<textarea>`. Degrades to styled native `<textarea>` if the tag never registers.
+ * @fires input - On every keystroke.
+ * @fires change - On blur.
  *
  * @prop {string} name - Name attribute for form submission
  * @prop {string} value - Current value of the textarea

package/types/src/autocomplete/autocomplete.d.ts

@@ -6,7 +6,18 @@ export type SchmancyAutocompleteChangeEvent = CustomEvent<{
 }>;
 declare const SchmancyAutocomplete_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * Autocomplete input component with filtering and multi-select support.
+ * Combobox with type-ahead filtering over a list of `<schmancy-option>` children. Single or multi-select. Form-associated.
+ *
+ * @element schmancy-autocomplete
+ * @summary Use when users need to pick from a known list of options but the list is too long for a plain select dropdown. Prefer schmancy-select for short static lists.
+ * @example
+ * <schmancy-autocomplete name="country" label="Country" placeholder="Start typing…">
+ *   <schmancy-option value="US">United States</schmancy-option>
+ *   <schmancy-option value="CA">Canada</schmancy-option>
+ *   <schmancy-option value="GB">United Kingdom</schmancy-option>
+ * </schmancy-autocomplete>
+ * @platform combobox change - Composed of a schmancy-input + a floating listbox populated from `<schmancy-option>` children. Multi-select renders selections as schmancy-input-chip chips. Degrades to a datalist-backed native input if the tag never registers.
+ * @fires change - `SchmancyAutocompleteChangeEvent` with `{ value }` (single) or `{ value, values }` (multi).
  *
  * @prop {string} name - Name attribute for form submission
  * @prop {string} label - Label text displayed above the input

package/types/src/button/button.d.ts

@@ -8,8 +8,13 @@ export type ButtonVariant = 'elevated' | 'filled' | 'filled tonal' | 'tonal' | '
 export type ButtonColor = 'primary' | 'secondary' | 'success' | 'error' | 'warning' | 'info' | 'neutral';
 declare const SchmancyButton_base: CustomElementConstructor & import("@mixins/index").Constructor<LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * A button component.
+ * Material Design button — primary interactive surface for triggering actions or navigation.
  * @element schmancy-button
+ * @summary Trigger actions or navigate. Form-associated; participates in native form submission.
+ * @example
+ * <schmancy-button variant="filled" @click=${() => save()}>Save</schmancy-button>
+ * <schmancy-button variant="outlined" href="/next">Continue</schmancy-button>
+ * @platform button click - Schmancy-skinned native `<button type="submit">`. When `href` is set, degrades to `<a href="…">`. Falls back to plain `<button>` styled with Tailwind if the tag never registers.
  * @slot - The default slot.
  * @slot prefix - The prefix slot.
  * @slot suffix - The suffix slot.

package/types/src/button/icon-button.d.ts

@@ -2,8 +2,14 @@ import { LitElement, PropertyValueMap } from 'lit';
 import { ButtonVariant } from './button';
 declare const SchmnacyIconButton_base: CustomElementConstructor & import("@mixins/index").Constructor<LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * An icon button component.
+ * Icon-only button for toolbar actions, close affordances, or overflow menus.
  * @element schmancy-icon-button
+ * @summary Compact round/square button wrapping a single icon glyph. Form-associated like schmancy-button.
+ * @example
+ * <schmancy-icon-button aria-label="Close" @click=${() => close()}>
+ *   <schmancy-icon>close</schmancy-icon>
+ * </schmancy-icon-button>
+ * @platform button click - Schmancy-skinned native `<button>` (or `<a>` when `href` is set). aria-label is required for a11y because there's no text content.
  * @slot - The default slot (usually an icon or glyph).
  * @csspart base - The underlying native `<button>` (or `<a>` when `href` is set).
  */

package/types/src/checkbox/checkbox.d.ts

@@ -5,9 +5,15 @@ export type schmancyCheckBoxChangeEvent = CustomEvent<{
 }>;
 declare const SchmancyCheckboxElement_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
+ * Binary checkbox for multi-select or boolean form fields. Wraps Material Web's `<md-checkbox>`; form-associated.
+ *
  * @element schmancy-checkbox
+ * @summary Use for "select many from a list" or any boolean that's part of a form submission. Prefer schmancy-switch for immediate-effect toggles.
+ * @example
+ * <schmancy-checkbox name="tos" required>I accept the terms</schmancy-checkbox>
+ * @platform checkbox change - Wraps `<md-checkbox>` from `@material/web`. Degrades to styled native `<input type="checkbox">` if the tag never registers.
  * @slot - The label for the checkbox.
- * @fires valueChange - Event fired when the checkbox value changes.
+ * @fires valueChange - `CustomEvent<{ value: boolean }>` when the checkbox is toggled.
  **/
 declare class SchmancyCheckboxElement extends SchmancyCheckboxElement_base {
     protected static shadowRootOptions: {

package/types/src/chips/chips.d.ts

@@ -2,6 +2,20 @@ import { PropertyValues } from 'lit';
 import type { FilterChipChangeEvent as SchmancyChipChangeEvent } from './filter-chip';
 import { SchmancyFilterChip as SchmancyChip } from './filter-chip';
 declare const SchmancyChips_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * Filter-chip group — container for selectable `<schmancy-chip>` children. Single or multi-select.
+ *
+ * @element schmancy-chips
+ * @summary Use for filtering or choosing from 2–8 mutually-visible options ("Status: active / paused / archived"). Prefer schmancy-select when the list gets long or vertical.
+ * @example
+ * <schmancy-chips multi @change=${(e) => this.filters = e.detail.values}>
+ *   <schmancy-chip value="active">Active</schmancy-chip>
+ *   <schmancy-chip value="paused">Paused</schmancy-chip>
+ *   <schmancy-chip value="archived">Archived</schmancy-chip>
+ * </schmancy-chips>
+ * @platform chip-group change - No direct native equivalent. Degrades to a styled schmancy-select with similar semantics if the tag never registers.
+ * @fires change - `CustomEvent<{ value: string }>` (single) or `{ values: string[] }` (multi).
+ */
 export default class SchmancyChips extends SchmancyChips_base {
     private value$;
     private values$;

package/types/src/chips/input-chip.d.ts

@@ -1,7 +1,7 @@
 import { LitElement } from 'lit';
 declare const SchmancyInputChip_base: import("../../mixins").Constructor<CustomElementConstructor> & import("../../mixins").Constructor<import("@mixins/tailwind.mixin").ITailwindElementMixin> & import("../../mixins").Constructor<LitElement> & import("../../mixins").Constructor<import("../../mixins").IBaseMixin>;
 /**
- * Input chip component - represents user-provided information that can be removed.
+ * Input chip — displays user-provided information (tags, recipients, filters) that can be removed but not toggled.
  *
  * IMPORTANT: Per Material Design 3 specification, input chips do NOT have selected state.
  * They represent discrete pieces of user input (like entered tags, selections from lists, etc.)
@@ -13,15 +13,15 @@ declare const SchmancyInputChip_base: import("../../mixins").Constructor<CustomE
  * - Tags or keywords entered by the user
  * - Selected items from a multi-select dropdown
  *
- * @fires click - Optional click event on chip body (value)
- * @fires remove - Dispatched when remove button is clicked (value)
- *
+ * @element schmancy-input-chip
+ * @summary Removable pill that represents a single user input value. No selected state — use schmancy-chip (filter chip) for toggleable options.
  * @example
- * ```html
  * <schmancy-input-chip value="john@example.com" avatar="/avatars/john.jpg">
  *   John Doe
  * </schmancy-input-chip>
- * ```
+ * @platform chip remove - No native equivalent. Composed of a labeled pill + close button. Degrades to a styled `<span>` with a trailing close `<button>` if the tag never registers.
+ * @fires click - Optional click event on chip body (value)
+ * @fires remove - Dispatched when remove button is clicked (value)
  */
 export declare class SchmancyInputChip extends SchmancyInputChip_base {
     /** Value identifier for the chip */

package/types/src/extra/countries/countries.d.ts

@@ -1,4 +1,14 @@
 declare const SchmancyCountriesSelect_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * Country picker — type-ahead autocomplete over the ISO 3166-1 country list. Form-associated.
+ *
+ * @element schmancy-select-countries
+ * @summary Drop-in replacement for schmancy-autocomplete when the options are specifically "every country". Pre-seeds the list from countries.data.
+ * @example
+ * <schmancy-select-countries name="country" label="Shipping country" required></schmancy-select-countries>
+ * @platform combobox change - Composes schmancy-autocomplete with a static options list. Value is the 2-letter ISO code.
+ * @fires change - `SchmancyAutocompleteChangeEvent` with `{ value: string }` (the ISO code).
+ */
 export declare class SchmancyCountriesSelect extends SchmancyCountriesSelect_base {
     static formAssociated: boolean;
     private internals?;

package/types/src/extra/timezone/timezone.d.ts

@@ -1,6 +1,13 @@
 declare const SchmancyTimezonesSelect_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * Timezone selector component with autocomplete filtering.
+ * Timezone picker — type-ahead autocomplete over the IANA tz database. Form-associated.
+ *
+ * @element schmancy-select-timezones
+ * @summary Drop-in replacement for schmancy-autocomplete when the options are IANA timezone names. Value is the IANA identifier ("America/Los_Angeles").
+ * @example
+ * <schmancy-select-timezones name="tz" label="Timezone" value="America/New_York"></schmancy-select-timezones>
+ * @platform combobox change - Composes schmancy-autocomplete with a static IANA timezones list.
+ * @fires change - `SchmancyAutocompleteChangeEvent` with `{ value: string }` (the IANA tz name).
  *
  * @prop {string} name - Name attribute for form submission
  * @prop {string} value - Selected timezone value

package/types/src/form/form.d.ts

@@ -1,6 +1,5 @@
 /**
- * A thin ergonomic wrapper around a native `<form>` element. Its children are
- * reparented into a `<form>` element in light DOM on connection, so:
+ * Ergonomic wrapper around a native `<form>`. Children are reparented into a light-DOM `<form>` on connection so form-associated custom elements resolve `internals.form` via native DOM ancestry.
  *
  * - Form-associated custom elements (FACE) resolve their `internals.form`
  *   correctly via native DOM ancestry.
@@ -16,6 +15,14 @@
  * lifting is the platform's.
  *
  * @element schmancy-form
+ * @summary Always wrap form-associated schmancy components in schmancy-form (or a native `<form>`) so `new FormData(form)` just works.
+ * @example
+ * <schmancy-form @submit=${(e) => console.log(Object.fromEntries(e.detail))}>
+ *   <schmancy-input name="email" type="email" required></schmancy-input>
+ *   <schmancy-input name="password" type="password" required></schmancy-input>
+ *   <schmancy-button type="submit" variant="filled">Sign in</schmancy-button>
+ * </schmancy-form>
+ * @platform form submit - Light-DOM native `<form>` element. Degrades to a `<form>` if the tag never registers — same semantics, just no CustomEvent translation.
  * @fires submit - `CustomEvent<FormData>` emitted when the form is submitted.
  * @fires reset - Emitted after the underlying form resets.
  */

package/types/src/input/input.d.ts

@@ -28,11 +28,18 @@ export type SchmancyInputEnterEvent = CustomEvent<EventDetails>;
 export type InputSize = 'xxs' | 'xs' | 'sm' | 'md' | 'lg';
 declare const SchmancyInput_base: import("@mixins/index").Constructor<import("@mixins/index").IFormFieldMixin> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * Enhanced version of the SchmancyInput component with improved form integration
- * and compatibility with legacy API.
+ * Single-line text input — the primary form-text primitive. Form-associated via ElementInternals, so it participates in native `<form>` submission, validation, and reset without additional wiring.
  *
- * This component uses the native form association API and maintains parity with
- * native input behaviors while providing a stylish, accessible interface.
+ * @element schmancy-input
+ * @summary Text input with Material Design styling, native form integration, and RxJS-debounced input/change/enter events.
+ * @example
+ * <schmancy-form @submit=${onSubmit}>
+ *   <schmancy-input name="email" type="email" label="Email" required></schmancy-input>
+ * </schmancy-form>
+ * @platform input change - Schmancy-skinned native `<input>`. Degrades to `<input class="…">` styled via Tailwind if the tag never registers.
+ * @fires input - `CustomEvent<{value: string}>` on every keystroke.
+ * @fires change - `CustomEvent<{value: string}>` on blur/change.
+ * @fires enter - `CustomEvent<{value: string}>` when user presses Enter.
  *
  * @prop {string} name - Name attribute for form submission (inherited from FormFieldMixin)
  * @prop {string} label - Label text for the form field (inherited from FormFieldMixin)

package/types/src/radio-group/radio-button.d.ts

@@ -1,6 +1,15 @@
 declare const RadioButton_base: import("@mixins/index").Constructor<import("@mixins/index").IFormFieldMixin> & import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * Radio button component for use within radio groups.
+ * Single radio button — always rendered as a child of `<schmancy-radio-group>`, never standalone.
+ *
+ * @element schmancy-radio-button
+ * @summary Low-level primitive. Use schmancy-radio-group and pass `.options` for the common path; only instantiate schmancy-radio-button directly when you need per-button custom rendering.
+ * @example
+ * <schmancy-radio-group name="plan">
+ *   <schmancy-radio-button value="free">Free</schmancy-radio-button>
+ *   <schmancy-radio-button value="pro" checked>Pro</schmancy-radio-button>
+ * </schmancy-radio-group>
+ * @platform radio change - Schmancy-skinned `<input type="radio">` semantics. Degrades to native radio if the tag never registers.
  *
  * @prop {string} name - Name attribute for grouping radio buttons
  * @prop {string} value - Value of this radio button

package/types/src/radio-group/radio-group.d.ts

@@ -6,6 +6,24 @@ export type SchmancyRadioGroupChangeEvent = CustomEvent<{
     value: string;
 }>;
 declare const RadioGroup_base: import("@mixins/index").Constructor<import("@mixins/index").IFormFieldMixin> & import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
+/**
+ * Radio-button group — single-select from a static list of mutually-exclusive options. Form-associated.
+ *
+ * @element schmancy-radio-group
+ * @summary Use for 2–5 mutually-exclusive options where all should stay visible ("Shipping: standard / express / overnight"). Prefer schmancy-select when the list grows.
+ * @example
+ * <schmancy-radio-group
+ *   name="shipping"
+ *   label="Shipping"
+ *   .options=${[
+ *     { label: 'Standard (5 days)', value: 'standard' },
+ *     { label: 'Express (2 days)', value: 'express' },
+ *     { label: 'Overnight', value: 'overnight' },
+ *   ]}
+ * ></schmancy-radio-group>
+ * @platform radiogroup change - Renders schmancy-radio-button children. Degrades to a fieldset with native `<input type="radio" name="…">` siblings if the tag never registers.
+ * @fires change - `SchmancyRadioGroupChangeEvent` with the selected `value`.
+ */
 export declare class RadioGroup extends RadioGroup_base {
     label: string;
     name: string;

package/types/src/select/select.d.ts

@@ -4,7 +4,18 @@ export type SchmancySelectChangeEvent = CustomEvent<{
 }>;
 declare const SchmancySelect_base: CustomElementConstructor & import("@mixins/index").Constructor<import("lit").LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * Select dropdown component with single and multi-select support.
+ * Dropdown selector — single or multi-select from a list of `<schmancy-option>` children. Form-associated.
+ *
+ * @element schmancy-select
+ * @summary Material Design dropdown with type-to-filter, keyboard nav, single or multi-select. Options are declared as `<schmancy-option>` children; value / values props sync with selection.
+ * @example
+ * <schmancy-select name="priority" label="Priority" value="medium">
+ *   <schmancy-option value="low">Low</schmancy-option>
+ *   <schmancy-option value="medium">Medium</schmancy-option>
+ *   <schmancy-option value="high">High</schmancy-option>
+ * </schmancy-select>
+ * @platform select change - Floating-UI-positioned listbox. Degrades to native `<select>` styled via Tailwind if the tag never registers, though multi-select UX is lost.
+ * @fires change - `SchmancySelectChangeEvent` with `{ value }` (single) or `{ value: string[] }` (multi).
  *
  * @prop {string} name - Name attribute for form submission
  * @prop {string} label - Label text displayed above the select

package/types/src/switch/switch.d.ts

@@ -4,12 +4,15 @@ export type SchmancySwitchChangeEvent = CustomEvent<{
 }>;
 declare const SchmancySwitch_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * Binary on/off control. Form-associated, keyboard-accessible, semantically a
- * switch (ARIA role="switch"). Distinct from `schmancy-checkbox`: a switch
- * represents an immediate state change, a checkbox represents a selection in
- * a form to be submitted.
+ * Binary on/off control with immediate effect. Form-associated, keyboard-accessible, semantically a switch (ARIA role="switch"). Distinct from `schmancy-checkbox`: a switch represents an immediate state change, a checkbox represents a selection in a form to be submitted.
  *
  * @element schmancy-switch
+ * @summary Use when flipping the control takes effect right away (e.g. "Dark mode", "Enable notifications"). Prefer schmancy-checkbox for form submissions.
+ * @example
+ * <schmancy-switch ?checked=${this.darkMode} @change=${(e) => this.darkMode = e.detail.value}>
+ *   Dark mode
+ * </schmancy-switch>
+ * @platform switch change - Accessible native `<button role="switch" aria-checked>` under the hood. No native HTML element exists; falls back to a styled checkbox if the tag never registers.
  * @fires change - `CustomEvent<{ value: boolean }>` when the state changes.
  * @attr checked - Initial checked state (also reflected via `value`).
  * @attr disabled - Disables interaction.

package/types/src/textarea/textarea.d.ts

@@ -1,7 +1,15 @@
 import { LitElement, type PropertyValues } from 'lit';
 declare const SchmancyTextarea_base: import("@mixins/index").Constructor<CustomElementConstructor> & import("@mixins/index").Constructor<import("@mixins/index").ITailwindElementMixin> & import("@mixins/index").Constructor<LitElement> & import("@mixins/index").Constructor<import("@mixins/index").IBaseMixin>;
 /**
- * Textarea component with auto-resize and form integration.
+ * Multi-line text input with auto-resize and form integration. Form-associated.
+ *
+ * @element schmancy-textarea
+ * @summary Textarea for freeform text — notes, descriptions, messages. Auto-grows with content up to a maxlength.
+ * @example
+ * <schmancy-textarea name="description" label="Description" rows="4" maxlength="500"></schmancy-textarea>
+ * @platform textarea change - Schmancy-skinned native `<textarea>`. Degrades to styled native `<textarea>` if the tag never registers.
+ * @fires input - On every keystroke.
+ * @fires change - On blur.
  *
  * @prop {string} name - Name attribute for form submission
  * @prop {string} value - Current value of the textarea