@mhmo91/schmancy 0.8.6 → 0.9.3

package/src/radio-group/readme.md

@@ -0,0 +1,315 @@
+# Schmancy Radio Group Component
+
+A flexible radio button group component with support for both declarative options and slotted radio buttons, built with reactive state management.
+
+## Overview
+
+The `schmancy-radio-group` component provides two usage patterns:
+- **Declarative options**: Pass an array of options for automatic radio button generation
+- **Slotted radio buttons**: Use individual `schmancy-radio-button` components for maximum flexibility
+- **Form integration**: Full HTML form support with validation
+- **Reactive state management**: Built with RxJS for predictable state updates
+- **TypeScript support**: Complete type safety with proper interfaces
+
+## Installation
+
+```typescript
+import '@schmancy/radio-group'
+// or
+import { RadioGroup, RadioButton } from '@schmancy/radio-group'
+```
+
+## Basic Usage
+
+### Declarative Options
+
+```html
+<schmancy-radio-group
+  name="fruit"
+  label="Select your favorite fruit"
+  value="apple"
+  required
+  .options=${[
+    { label: 'Apple', value: 'apple' },
+    { label: 'Banana', value: 'banana' },
+    { label: 'Orange', value: 'orange' }
+  ]}
+></schmancy-radio-group>
+```
+
+```typescript
+// Setting value programmatically
+const radioGroup = document.querySelector('schmancy-radio-group')
+radioGroup.value = 'banana'
+
+// Getting selected value
+console.log(radioGroup.value) // 'banana'
+```
+
+### Slotted Radio Buttons
+
+For more control over individual radio buttons:
+
+```html
+<schmancy-radio-group name="size" label="Select size" value="medium">
+  <schmancy-radio-button value="small">
+    <span slot="label">Small (S)</span>
+  </schmancy-radio-button>
+  <schmancy-radio-button value="medium">
+    <span slot="label">Medium (M)</span>
+  </schmancy-radio-button>
+  <schmancy-radio-button value="large">
+    <span slot="label">Large (L)</span>
+  </schmancy-radio-button>
+</schmancy-radio-group>
+```
+
+## Properties
+
+### SchmancyRadioGroup
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `name` | `string` | `''` | Form field name for submission |
+| `value` | `string` | `''` | Currently selected value |
+| `label` | `string` | `''` | Group label displayed above options |
+| `options` | `SchmancyRadioGroupOption[]` | `[]` | Array of options for declarative mode |
+| `required` | `boolean` | `false` | Make field required for form validation |
+
+### SchmancyRadioButton
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `string` | `''` | Value of this radio button |
+| `checked` | `boolean` | `false` | Whether this button is selected |
+| `disabled` | `boolean` | `false` | Disable this radio button |
+| `name` | `string` | `''` | Form field name (usually inherited from group) |
+
+## Types
+
+```typescript
+interface SchmancyRadioGroupOption {
+  label: string
+  value: string
+}
+
+interface SchmancyRadioGroupChangeEvent extends CustomEvent {
+  detail: {
+    value: string
+  }
+}
+```
+
+## Events
+
+### SchmancyRadioGroupChangeEvent
+
+The component dispatches a `change` event when the selection changes:
+
+```typescript
+// Event handling
+radioGroup.addEventListener('change', (e: SchmancyRadioGroupChangeEvent) => {
+  console.log('Selected value:', e.detail.value)
+})
+```
+
+## Form Integration
+
+The component fully supports HTML form integration:
+
+```html
+<form id="preferencesForm">
+  <schmancy-radio-group
+    name="theme"
+    label="Theme Preference"
+    required
+    .options=${[
+      { label: 'Light Mode', value: 'light' },
+      { label: 'Dark Mode', value: 'dark' },
+      { label: 'Auto (System)', value: 'auto' }
+    ]}
+  ></schmancy-radio-group>
+
+  <schmancy-radio-group
+    name="notifications"
+    label="Notification Frequency"
+    value="daily"
+    .options=${[
+      { label: 'Immediate', value: 'immediate' },
+      { label: 'Daily Digest', value: 'daily' },
+      { label: 'Weekly Summary', value: 'weekly' },
+      { label: 'Disabled', value: 'never' }
+    ]}
+  ></schmancy-radio-group>
+
+  <button type="submit">Save Preferences</button>
+</form>
+```
+
+```typescript
+// Form submission handling
+document.getElementById('preferencesForm').addEventListener('submit', (e) => {
+  e.preventDefault()
+  const formData = new FormData(e.target)
+
+  console.log({
+    theme: formData.get('theme'),
+    notifications: formData.get('notifications')
+  })
+})
+```
+
+## Advanced Examples
+
+### Mixed Usage Pattern
+
+```html
+<schmancy-radio-group name="plan" label="Select Plan" value="pro">
+  <!-- Custom radio button with rich content -->
+  <schmancy-radio-button value="free">
+    <div slot="label" class="flex items-center justify-between w-full">
+      <div>
+        <div class="font-semibold">Free Plan</div>
+        <div class="text-sm text-gray-500">Basic features</div>
+      </div>
+      <div class="text-lg font-bold">$0</div>
+    </div>
+  </schmancy-radio-button>
+
+  <!-- Another custom radio button -->
+  <schmancy-radio-button value="pro">
+    <div slot="label" class="flex items-center justify-between w-full">
+      <div>
+        <div class="font-semibold">Pro Plan</div>
+        <div class="text-sm text-gray-500">Advanced features</div>
+      </div>
+      <div class="text-lg font-bold">$19/mo</div>
+    </div>
+  </schmancy-radio-button>
+
+  <schmancy-radio-button value="enterprise">
+    <div slot="label" class="flex items-center justify-between w-full">
+      <div>
+        <div class="font-semibold">Enterprise Plan</div>
+        <div class="text-sm text-gray-500">All features + support</div>
+      </div>
+      <div class="text-lg font-bold">$99/mo</div>
+    </div>
+  </schmancy-radio-button>
+</schmancy-radio-group>
+```
+
+### Dynamic Options
+
+```typescript
+// Populate options dynamically
+const radioGroup = document.querySelector<RadioGroup>('schmancy-radio-group')
+
+async function loadCategories() {
+  const categories = await fetch('/api/categories').then(r => r.json())
+
+  radioGroup.options = categories.map(cat => ({
+    label: cat.name,
+    value: cat.id
+  }))
+}
+
+// Set initial selection
+radioGroup.value = 'default-category'
+
+// Listen for changes
+radioGroup.addEventListener('change', (e: SchmancyRadioGroupChangeEvent) => {
+  console.log('Category selected:', e.detail.value)
+  updateContentForCategory(e.detail.value)
+})
+```
+
+### Standalone Radio Button
+
+Radio buttons can also be used independently outside of a radio group:
+
+```html
+<schmancy-radio-button
+  name="standalone"
+  value="option1"
+  checked
+>
+  <span slot="label">I agree to the terms and conditions</span>
+</schmancy-radio-button>
+```
+
+```typescript
+const standaloneRadio = document.querySelector('schmancy-radio-button')
+standaloneRadio.addEventListener('change', (e) => {
+  console.log('Checkbox changed:', e.detail.value)
+})
+```
+
+## Accessibility Features
+
+The component implements comprehensive accessibility features:
+
+### Keyboard Navigation
+- **Tab**: Move focus between radio buttons
+- **Arrow Keys**: Navigate between options within a group
+- **Space**: Select the focused radio button
+
+### ARIA Attributes
+The component automatically manages ARIA attributes:
+- `role="radiogroup"` on the container
+- `role="radio"` on individual buttons
+- `aria-checked` state management
+- `aria-required` for required groups
+- `aria-disabled` for disabled buttons
+
+### Screen Reader Support
+Full screen reader compatibility with proper announcements for:
+- Group labels and descriptions
+- Selected values
+- Required field states
+
+## TypeScript Usage
+
+```typescript
+import {
+  RadioGroup,
+  RadioButton,
+  SchmancyRadioGroupChangeEvent,
+  SchmancyRadioGroupOption
+} from '@schmancy/radio-group'
+
+// Create options with type safety
+const themeOptions: SchmancyRadioGroupOption[] = [
+  { label: 'Light', value: 'light' },
+  { label: 'Dark', value: 'dark' }
+]
+
+// Get typed reference
+const radioGroup = document.querySelector<RadioGroup>('schmancy-radio-group')
+
+// Type-safe value setting
+radioGroup.options = themeOptions
+radioGroup.value = 'light'
+
+// Typed event handling
+radioGroup?.addEventListener('change', (event: SchmancyRadioGroupChangeEvent) => {
+  const selectedValue: string = event.detail.value
+  console.log('Selected:', selectedValue)
+})
+```
+
+## Browser Support
+
+The component uses modern web standards and requires browsers that support:
+- Custom Elements v1
+- Shadow DOM v1
+- ES2015+
+- CSS Custom Properties
+
+For older browsers, consider using appropriate polyfills.
+
+## Related Components
+
+- `schmancy-radio-button` - Individual radio button component
+- `schmancy-checkbox` - Checkbox component for multi-select scenarios
+- `schmancy-select` - Dropdown selection component

package/src/range/index.ts

@@ -0,0 +1 @@
+export * from './range'

package/src/range/range.ts

@@ -0,0 +1,102 @@
+import { TailwindElement } from '@mixins/index'
+import { css, html } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+import { when } from 'lit/directives/when.js'
+
+export type SchmancyRangeChangeEvent = CustomEvent<{ value: number }>
+
+/**
+ * @element schmancy-range
+ * Range input (numeric slider).
+ * @fires change - Fires on value change with { value: number }
+ */
+@customElement('schmancy-range')
+export class SchmancyRange extends TailwindElement(css`
+	input[type='range'] {
+		-webkit-appearance: none;
+		appearance: none;
+		width: 100%;
+		height: 4px;
+		border-radius: 2px;
+		background: linear-gradient(
+			to right,
+			var(--color-primary, #6750a4) 0%,
+			var(--color-primary, #6750a4) var(--range-progress, 0%),
+			color-mix(in srgb, var(--color-primary, #6750a4) 30%, transparent) var(--range-progress, 0%),
+			color-mix(in srgb, var(--color-primary, #6750a4) 30%, transparent) 100%
+		);
+		outline: none;
+		cursor: pointer;
+	}
+	input[type='range']:disabled {
+		opacity: 0.38;
+		cursor: not-allowed;
+	}
+	input[type='range']::-webkit-slider-thumb {
+		-webkit-appearance: none;
+		appearance: none;
+		width: 20px;
+		height: 20px;
+		border-radius: 50%;
+		background: var(--color-primary, #6750a4);
+		cursor: pointer;
+		transition: box-shadow 0.1s ease;
+	}
+	input[type='range']::-webkit-slider-thumb:hover {
+		box-shadow: 0 0 0 8px color-mix(in srgb, var(--color-primary, #6750a4) 12%, transparent);
+	}
+	input[type='range']::-moz-range-thumb {
+		width: 20px;
+		height: 20px;
+		border-radius: 50%;
+		border: none;
+		background: var(--color-primary, #6750a4);
+		cursor: pointer;
+	}
+`) {
+	@property({ type: Number }) min = 0
+	@property({ type: Number }) max = 1
+	@property({ type: Number }) step = 0.01
+	@property({ type: Number }) value = 0
+	@property({ type: String }) label?: string
+	@property({ type: Boolean }) disabled = false
+
+	private get progress(): string {
+		return `${((this.value - this.min) / (this.max - this.min)) * 100}%`
+	}
+
+	render() {
+		return html`
+			<div class="flex flex-col gap-1 w-full">
+				${when(
+					this.label,
+					() => html`
+						<div class="flex justify-between items-center">
+							<schmancy-typography type="label" token="sm" class="text-surface-on">${this.label}</schmancy-typography>
+							<schmancy-typography type="label" token="sm" class="text-surface-on opacity-60">${this.value}</schmancy-typography>
+						</div>
+					`,
+				)}
+				<input
+					type="range"
+					.min=${String(this.min)}
+					.max=${String(this.max)}
+					.step=${String(this.step)}
+					.value=${String(this.value)}
+					?disabled=${this.disabled}
+					style="--range-progress: ${this.progress}"
+					@input=${(e: Event) => {
+						this.value = Number((e.target as HTMLInputElement).value)
+						this.dispatchEvent(new CustomEvent('change', { detail: { value: this.value }, bubbles: true, composed: true }))
+					}}
+				/>
+			</div>
+		`
+	}
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'schmancy-range': SchmancyRange
+	}
+}

package/src/rxjs-utils/index.ts

@@ -0,0 +1,6 @@
+export * from './mutation-observer';
+export * from './waitForElement';
+export * from './waitForElementAll';
+export * from './waitForElements';
+export * from './waitForElementsAll';
+export * from './waitUntil';

package/src/rxjs-utils/mutation-observer.ts

@@ -0,0 +1,22 @@
+import { Observable } from 'rxjs'
+
+export const mutationObserver = (
+	target: HTMLElement,
+	config: MutationObserverInit = {
+		attributes: true,
+		childList: true,
+		subtree: true,
+	},
+): Observable<MutationRecord[]> => {
+	return new Observable(observer => {
+		const mutation = new MutationObserver(mutations => {
+			observer.next(mutations)
+		})
+		mutation.observe(target, config)
+		const unsubscribe = () => {
+			mutation.disconnect()
+		}
+		return unsubscribe
+	})
+}
+export default mutationObserver

package/src/rxjs-utils/waitForElement.ts

@@ -0,0 +1,33 @@
+import { catchError, filter, map, startWith, take, tap, throwError, timeout } from 'rxjs'
+import observeOnMutation from './mutation-observer'
+
+/**
+ *
+ * @returns An observable that emits the element when it is found
+ * @example waitForElement('button').subscribe(button => button.click())
+ * @example waitForElement('button', 10000).subscribe(button => button.click())
+ * @example waitForElement('button', undefiend).subscribe(button => button.click())
+ */
+export default function waitForElement<T extends Element>(
+  /**
+   * @param selector The selector to use to find the element
+   * @type { string }
+   */
+  selector: string,
+  /**
+   * @param timeoutAfter How long to wait for the element to appear before throwing an error
+   * @default 5000
+   * @type { number | undefined }
+   * @description If you don't want to wait for the element to appear, pass `undefined` as the second argument
+   */
+  timeoutAfter = 5000,
+) {
+  return observeOnMutation(document.body).pipe(
+    startWith(document.body),
+    map(() => document.querySelector<T>(selector)),
+    filter(Boolean),
+    take(1),
+    timeoutAfter ? timeout(timeoutAfter) : tap(),
+    catchError(() => throwError(() => 'Selector timeout for ' + selector)),
+  )
+}

package/src/rxjs-utils/waitForElementAll.ts

@@ -0,0 +1,34 @@
+import { catchError, filter, map, startWith, take, tap, throwError, timeout } from 'rxjs'
+import observeOnMutation from './mutation-observer'
+
+/**
+ *
+ * @returns An observable that emits the element when it is found
+ * @example waitForElement('button').subscribe(button => button.click())
+ * @example waitForElement('button', 10000).subscribe(button => button.click())
+ * @example waitForElement('button', undefiend).subscribe(button => button.click())
+ */
+export default function waitForElementAll<T extends Element>(
+  /**
+   * @param selector The selector to use to find the element
+   * @type { string }
+   */
+  selector: string,
+  /**
+   * @param timeoutAfter How long to wait for the element to appear before throwing an error
+   * @default 5000
+   * @type { number | undefined }
+   * @description If you don't want to wait for the element to appear, pass `undefined` as the second argument
+   */
+  timeoutAfter = 5000,
+) {
+  return observeOnMutation(document.body).pipe(
+    startWith(document.body),
+    map(() => document.querySelectorAll<T>(selector)),
+    filter(arr => arr.length > 0),
+    take(1),
+    map(elements => Array.from(elements)),
+    timeoutAfter ? timeout(timeoutAfter) : tap(),
+    catchError(() => throwError(() => 'Selector timeout for ' + selector)),
+  )
+}

package/src/rxjs-utils/waitForElements.ts

@@ -0,0 +1,40 @@
+import { filter, map, startWith, take, tap, timeout } from 'rxjs'
+import { isPresent } from 'ts-is-present'
+import observeOnMutation from './mutation-observer'
+
+/**
+ * @returns An observable that emits the elements when they are found
+ * @description This function is useful when you want to wait for multiple elements to appear
+ * @example waitForElements(['button', 'input']).subscribe(([button, input]) => button.click())
+ * @returns
+ */
+export default function waitForElements<T extends Array<T>>(
+  /**
+   * @param selectors The selectors to use to find the elements
+   * @type { string[] }
+   * @description The order of the elements in the array is the same as the order of the elements in the emitted array
+   */
+  selectors: string[],
+  /**
+   * @param timeoutAfter How long to wait for the elements to appear before throwing an error
+   * @default 5000
+   * @type { number | undefined }
+   * @description If you don't want to wait for the elements to appear, pass `undefined` as the second argument
+   */
+  timeoutAfter = 5000,
+) {
+  return observeOnMutation(document.body).pipe(
+    startWith(document.body),
+    filter(() => selectors.every(s => !!document.querySelector(s))),
+    take(1),
+    map(() => selectors.map(s => document.querySelector(s)).filter(isPresent)), // why filter again? see https://github.com/Microsoft/TypeScript/issues/16069
+    map(elements => {
+      if (elements.length === selectors.length) {
+        return elements
+      } else {
+        throw new Error('Not all elements were found')
+      }
+    }),
+    timeoutAfter ? timeout(timeoutAfter) : tap(),
+  )
+}

package/src/rxjs-utils/waitForElementsAll.ts

@@ -0,0 +1,42 @@
+import { filter, map, startWith, take, tap, timeout } from 'rxjs'
+import { isPresent } from 'ts-is-present'
+import observeOnMutation from './mutation-observer'
+
+/**
+ * @returns An observable that emits the elements when they are found
+ * @description This function is useful when you want to wait for multiple elements to appear
+ * @example waitForElements(['button', 'input']).subscribe(([button, input]) => button.click())
+ * @returns
+ */
+export default function waitForElementsAll<T extends Array<T>>(
+  /**
+   * @param selectors The selectors to use to find the elements
+   * @type { string[] }
+   * @description The order of the elements in the array is the same as the order of the elements in the emitted array
+   */
+  selectors: string[],
+  /**
+   * @param timeoutAfter How long to wait for the elements to appear before throwing an error
+   * @default 5000
+   * @type { number | undefined }
+   * @description If you don't want to wait for the elements to appear, pass `undefined` as the second argument
+   */
+  timeoutAfter = 5000,
+) {
+  return observeOnMutation(document.body).pipe(
+    startWith(document.body),
+    filter(() => selectors.every(s => !!document.querySelector(s))),
+    take(1),
+    map(() =>
+      selectors.map(s => document.querySelectorAll(s)).filter(isPresent),
+    ), // why filter again? see https://github.com/Microsoft/TypeScript/issues/16069
+    map(elements => {
+      if (elements.length === selectors.length) {
+        return elements
+      } else {
+        throw new Error('Not all elements were found')
+      }
+    }),
+    timeoutAfter ? timeout(timeoutAfter) : tap(),
+  )
+}

package/src/rxjs-utils/waitUntil.ts

@@ -0,0 +1,16 @@
+import { filter, startWith, take, timeout } from 'rxjs'
+import observeOnMutation from './mutation-observer'
+
+export default function waitUntil(
+  selectors: Array<string>,
+  timeoutAfter = 5000,
+) {
+  return observeOnMutation(document.body).pipe(
+    startWith(document.body),
+    filter(() =>
+      selectors.every(selector => !!document.querySelector(selector)),
+    ),
+    take(1),
+    timeout(timeoutAfter),
+  )
+}