@data-slot/toggle 0.2.10

package/README.md

@@ -0,0 +1,197 @@
+# @data-slot/toggle
+
+Headless toggle button component for vanilla JavaScript. Accessible, unstyled, tiny.
+
+## Installation
+
+```bash
+npm install @data-slot/toggle
+```
+
+## Quick Start
+
+```html
+<button data-slot="toggle">Bold</button>
+<button data-slot="toggle" data-default-pressed>Italic</button>
+
+<script type="module">
+  import { create } from "@data-slot/toggle";
+
+  const controllers = create();
+</script>
+```
+
+## API
+
+### `create(scope?)`
+
+Auto-discover and bind all toggle instances in a scope (defaults to `document`).
+
+```typescript
+import { create } from "@data-slot/toggle";
+
+const controllers = create(); // Returns ToggleController[]
+```
+
+### `createToggle(root, options?)`
+
+Create a controller for a specific element.
+
+```typescript
+import { createToggle } from "@data-slot/toggle";
+
+const toggle = createToggle(element, {
+  defaultPressed: false,
+  disabled: false,
+  onPressedChange: (pressed) => console.log(pressed),
+});
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `defaultPressed` | `boolean` | `false` | Initial pressed state |
+| `disabled` | `boolean` | `false` | Disabled state |
+| `onPressedChange` | `(pressed: boolean) => void` | `undefined` | Callback when state changes |
+
+### Data Attributes
+
+Options can also be set via data attributes on the root element. JS options take precedence.
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `data-default-pressed` | boolean | `false` | Initial pressed state |
+| `data-disabled` | boolean | `false` | Disabled state |
+
+```html
+<!-- Initially pressed toggle -->
+<button data-slot="toggle" data-default-pressed>Bold</button>
+```
+
+### Controller
+
+| Method/Property | Description |
+|-----------------|-------------|
+| `toggle()` | Toggle the pressed state (ignores disabled) |
+| `press()` | Set pressed to true (ignores disabled) |
+| `release()` | Set pressed to false (ignores disabled) |
+| `pressed` | Current pressed state (readonly `boolean`) |
+| `destroy()` | Cleanup all event listeners |
+
+**Note:** Controller methods always work, even when disabled. This allows programmatic control regardless of user interaction state. If you need to check disabled state before calling controller methods, check the element's attributes yourself.
+
+## Markup Structure
+
+```html
+<button data-slot="toggle">Label</button>
+```
+
+The toggle is a simple single-element component. Always use a native `<button>` element—keyboard support (Enter/Space) and focus handling are only guaranteed with `<button>`. Non-button elements (e.g., `<div>`, `<span>`) are not recommended and would require manual keyboard handling.
+
+## Styling
+
+### State Attributes
+
+The component sets these attributes for styling:
+
+- `aria-pressed="true|false"` - ARIA state
+- `data-state="on|off"` - CSS styling hook
+
+### Basic Styling
+
+```css
+/* Unpressed state */
+[data-slot="toggle"] {
+  background: #e5e7eb;
+  border: none;
+  padding: 0.5rem 1rem;
+  cursor: pointer;
+}
+
+/* Pressed state */
+[data-slot="toggle"][data-state="on"] {
+  background: #3b82f6;
+  color: white;
+}
+
+/* Or use aria-pressed */
+[data-slot="toggle"][aria-pressed="true"] {
+  background: #3b82f6;
+  color: white;
+}
+
+/* Disabled state */
+[data-slot="toggle"][aria-disabled="true"] {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```
+
+### Tailwind Example
+
+```html
+<button
+  data-slot="toggle"
+  class="px-4 py-2 rounded bg-gray-200 data-[state=on]:bg-blue-500 data-[state=on]:text-white aria-disabled:opacity-50"
+>
+  Bold
+</button>
+```
+
+## Keyboard Support
+
+The toggle uses a native `<button>` element, so keyboard support is automatic:
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Toggle state |
+| `Space` | Toggle state |
+
+## Disabled Behavior
+
+When disabled (via `disabled` option, `data-disabled` attribute, native `disabled` attribute, or `aria-disabled="true"`):
+
+| Input | Blocked? |
+|-------|----------|
+| Click / Enter / Space | Yes |
+| `toggle:set` event | Yes |
+| Controller methods (`toggle()`, `press()`, `release()`) | No |
+
+For `<button>` elements, the `disabled` option sets both the native `disabled` attribute and `aria-disabled="true"`. For other elements, only `aria-disabled` is set.
+
+## Accessibility
+
+The component automatically handles:
+
+- `aria-pressed` state on the button
+- Native `disabled` and `aria-disabled` when disabled (for buttons)
+- `type="button"` to prevent form submission
+
+## Events
+
+Listen for changes via custom events:
+
+```javascript
+element.addEventListener("toggle:change", (e) => {
+  console.log("Pressed:", e.detail.pressed);
+});
+```
+
+Control the toggle via events (ignored when disabled):
+
+```javascript
+// Set to specific state
+element.dispatchEvent(
+  new CustomEvent("toggle:set", { detail: { pressed: true } })
+);
+
+// Or with just a boolean
+element.dispatchEvent(
+  new CustomEvent("toggle:set", { detail: true })
+);
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1 @@
+const e=(e,t)=>[...e.querySelectorAll(`[data-slot="${t}"]`)],t=new WeakMap;function n(e,n,r){if(typeof process<`u`&&process.env?.NODE_ENV===`production`)return;let i=t.get(e);i||(i=new Set,t.set(e,i)),!i.has(n)&&(i.add(n),console.warn(`[@data-slot] ${r}`))}function r(e){let t=`data-${e.replace(/([A-Z])/g,`-$1`).toLowerCase()}`,n=`data-${e}`;return t===n?[t]:[t,n]}function i(e,t){for(let n of r(t))if(e.hasAttribute(n))return e.getAttribute(n);return null}function a(e,t){return r(t).some(t=>e.hasAttribute(t))}const o=new Set([``,`true`,`1`,`yes`]),s=new Set([`false`,`0`,`no`]);function c(e,t){if(!a(e,t))return;let r=i(e,t);if(r===null)return;let c=r.toLowerCase();if(o.has(c))return!0;if(s.has(c))return!1;n(e,t,`Invalid boolean value "${r}" for data-${t}. Expected: true/false/1/0/yes/no or empty.`)}const l=(e,t,n)=>{n===null?e.removeAttribute(`aria-${t}`):e.setAttribute(`aria-${t}`,String(n))};function u(e,t,n,r){return e.addEventListener(t,n,r),()=>e.removeEventListener(t,n,r)}const d=(e,t,n)=>e.dispatchEvent(new CustomEvent(t,{bubbles:!0,detail:n}));function f(e,t={}){let n=t.defaultPressed??c(e,`defaultPressed`)??!1,r=t.disabled??c(e,`disabled`)??!1,i=t.onPressedChange,a=n,o=[],s=()=>e.hasAttribute(`disabled`)||e.getAttribute(`aria-disabled`)===`true`,f=(t,n=!1)=>{a===t&&!n||(a=t,l(e,`pressed`,a),e.dataset.state=a?`on`:`off`,n||(d(e,`toggle:change`,{pressed:a}),i?.(a)))};return r&&(e.tagName===`BUTTON`&&e.setAttribute(`disabled`,``),e.setAttribute(`aria-disabled`,`true`)),e.tagName===`BUTTON`&&!e.hasAttribute(`type`)&&e.setAttribute(`type`,`button`),f(a,!0),o.push(u(e,`click`,()=>{s()||f(!a)})),o.push(u(e,`toggle:set`,e=>{if(s())return;let t=e.detail,n=typeof t==`boolean`?t:t?.pressed;typeof n==`boolean`&&f(n)})),{toggle:()=>f(!a),press:()=>f(!0),release:()=>f(!1),get pressed(){return a},destroy:()=>{o.forEach(e=>e()),o.length=0,p.delete(e)}}}const p=new WeakSet;function m(t=document){let n=[];for(let r of e(t,`toggle`)){if(p.has(r))continue;p.add(r),n.push(f(r))}return n}exports.create=m,exports.createToggle=f;

package/dist/index.d.cts

@@ -0,0 +1,29 @@
+//#region src/index.d.ts
+interface ToggleOptions {
+  /** Initial pressed state */
+  defaultPressed?: boolean;
+  /** Disabled state */
+  disabled?: boolean;
+  /** Callback when pressed state changes */
+  onPressedChange?: (pressed: boolean) => void;
+}
+interface ToggleController {
+  /** Toggle the pressed state (always works, ignores disabled) */
+  toggle(): void;
+  /** Set pressed to true (always works, ignores disabled) */
+  press(): void;
+  /** Set pressed to false (always works, ignores disabled) */
+  release(): void;
+  /** Current pressed state */
+  readonly pressed: boolean;
+  /** Cleanup all event listeners */
+  destroy(): void;
+}
+declare function createToggle(root: HTMLElement, options?: ToggleOptions): ToggleController;
+/**
+ * Find and bind all toggle instances in a scope
+ * Returns array of controllers for programmatic access
+ */
+declare function create(scope?: ParentNode): ToggleController[];
+//#endregion
+export { ToggleController, ToggleOptions, create, createToggle };

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+//#region src/index.d.ts
+interface ToggleOptions {
+  /** Initial pressed state */
+  defaultPressed?: boolean;
+  /** Disabled state */
+  disabled?: boolean;
+  /** Callback when pressed state changes */
+  onPressedChange?: (pressed: boolean) => void;
+}
+interface ToggleController {
+  /** Toggle the pressed state (always works, ignores disabled) */
+  toggle(): void;
+  /** Set pressed to true (always works, ignores disabled) */
+  press(): void;
+  /** Set pressed to false (always works, ignores disabled) */
+  release(): void;
+  /** Current pressed state */
+  readonly pressed: boolean;
+  /** Cleanup all event listeners */
+  destroy(): void;
+}
+declare function createToggle(root: HTMLElement, options?: ToggleOptions): ToggleController;
+/**
+ * Find and bind all toggle instances in a scope
+ * Returns array of controllers for programmatic access
+ */
+declare function create(scope?: ParentNode): ToggleController[];
+//#endregion
+export { ToggleController, ToggleOptions, create, createToggle };

package/dist/index.js

@@ -0,0 +1 @@
+const e=(e,t)=>[...e.querySelectorAll(`[data-slot="${t}"]`)],t=new WeakMap;function n(e,n,r){if(typeof process<`u`&&process.env?.NODE_ENV===`production`)return;let i=t.get(e);i||(i=new Set,t.set(e,i)),!i.has(n)&&(i.add(n),console.warn(`[@data-slot] ${r}`))}function r(e){let t=`data-${e.replace(/([A-Z])/g,`-$1`).toLowerCase()}`,n=`data-${e}`;return t===n?[t]:[t,n]}function i(e,t){for(let n of r(t))if(e.hasAttribute(n))return e.getAttribute(n);return null}function a(e,t){return r(t).some(t=>e.hasAttribute(t))}const o=new Set([``,`true`,`1`,`yes`]),s=new Set([`false`,`0`,`no`]);function c(e,t){if(!a(e,t))return;let r=i(e,t);if(r===null)return;let c=r.toLowerCase();if(o.has(c))return!0;if(s.has(c))return!1;n(e,t,`Invalid boolean value "${r}" for data-${t}. Expected: true/false/1/0/yes/no or empty.`)}const l=(e,t,n)=>{n===null?e.removeAttribute(`aria-${t}`):e.setAttribute(`aria-${t}`,String(n))};function u(e,t,n,r){return e.addEventListener(t,n,r),()=>e.removeEventListener(t,n,r)}const d=(e,t,n)=>e.dispatchEvent(new CustomEvent(t,{bubbles:!0,detail:n}));function f(e,t={}){let n=t.defaultPressed??c(e,`defaultPressed`)??!1,r=t.disabled??c(e,`disabled`)??!1,i=t.onPressedChange,a=n,o=[],s=()=>e.hasAttribute(`disabled`)||e.getAttribute(`aria-disabled`)===`true`,f=(t,n=!1)=>{a===t&&!n||(a=t,l(e,`pressed`,a),e.dataset.state=a?`on`:`off`,n||(d(e,`toggle:change`,{pressed:a}),i?.(a)))};return r&&(e.tagName===`BUTTON`&&e.setAttribute(`disabled`,``),e.setAttribute(`aria-disabled`,`true`)),e.tagName===`BUTTON`&&!e.hasAttribute(`type`)&&e.setAttribute(`type`,`button`),f(a,!0),o.push(u(e,`click`,()=>{s()||f(!a)})),o.push(u(e,`toggle:set`,e=>{if(s())return;let t=e.detail,n=typeof t==`boolean`?t:t?.pressed;typeof n==`boolean`&&f(n)})),{toggle:()=>f(!a),press:()=>f(!0),release:()=>f(!1),get pressed(){return a},destroy:()=>{o.forEach(e=>e()),o.length=0,p.delete(e)}}}const p=new WeakSet;function m(t=document){let n=[];for(let r of e(t,`toggle`)){if(p.has(r))continue;p.add(r),n.push(f(r))}return n}export{m as create,f as createToggle};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@data-slot/toggle",
+  "version": "0.2.10",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown"
+  },
+  "devDependencies": {
+    "@data-slot/core": "workspace:*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bejamas/data-slot",
+    "directory": "packages/toggle"
+  },
+  "keywords": [
+    "headless",
+    "ui",
+    "toggle",
+    "vanilla",
+    "data-slot"
+  ],
+  "license": "MIT"
+}