npm - @data-slot/toggle-group - Versions diffs - 0.2.10 - Mend

@data-slot/toggle-group 0.2.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,153 @@
+# @data-slot/toggle-group
+A group of toggle buttons with shared state, supporting single or multiple selection.
+## Installation
+```bash
+bun add @data-slot/toggle-group
+```
+## Usage
+### Basic Markup
+```html
+<!-- Single selection (default) -->
+<div data-slot="toggle-group" data-default-value="center">
+  <button data-slot="toggle-group-item" data-value="left">Left</button>
+  <button data-slot="toggle-group-item" data-value="center">Center</button>
+  <button data-slot="toggle-group-item" data-value="right">Right</button>
+</div>
+<!-- Multiple selection -->
+<div data-slot="toggle-group" data-multiple data-default-value="bold italic">
+  <button data-slot="toggle-group-item" data-value="bold">B</button>
+  <button data-slot="toggle-group-item" data-value="italic">I</button>
+  <button data-slot="toggle-group-item" data-value="underline">U</button>
+</div>
+```
+### JavaScript
+```javascript
+import { create, createToggleGroup } from "@data-slot/toggle-group";
+// Auto-discover and bind all toggle-group elements
+const controllers = create();
+// Or target a specific element
+const group = createToggleGroup(element, {
+  defaultValue: "center",
+  multiple: false,
+  orientation: "horizontal",
+  loop: true,
+  onValueChange: (value) => console.log(value),
+});
+// Programmatic control
+group.setValue("left");
+group.toggle("bold");
+console.log(group.value); // ["left"]
+// Cleanup
+group.destroy();
+```
+## Options
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `defaultValue` | `string \| string[]` | `[]` | Initial selected value(s). For multiple values, use array or space-separated string. |
+| `multiple` | `boolean` | `false` | Allow multiple selections. |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Orientation for keyboard navigation. |
+| `loop` | `boolean` | `true` | Wrap keyboard focus at ends. |
+| `disabled` | `boolean` | `false` | Disable the entire group. |
+| `onValueChange` | `(value: string[]) => void` | - | Callback when selection changes. |
+## Data Attributes
+### Root Element
+| Attribute | Description |
+|-----------|-------------|
+| `data-slot="toggle-group"` | Required. Identifies the root element. |
+| `data-default-value` | Initial selected value(s). Space-separated for multiple values. |
+| `data-multiple` | Enable multiple selection mode. |
+| `data-orientation` | `"horizontal"` or `"vertical"` for keyboard navigation. |
+| `data-disabled` | Disable the entire group. |
+### Item Elements
+| Attribute | Description |
+|-----------|-------------|
+| `data-slot="toggle-group-item"` | Required. Identifies an item. |
+| `data-value` | Required. The value associated with this item. |
+| `data-disabled` | Disable this specific item. |
+### State Attributes (set by component)
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `aria-pressed` | `"true"` \| `"false"` | Whether item is pressed. |
+| `data-state` | `"on"` \| `"off"` | Visual state for styling. |
+| `data-value` (on root) | Space-separated values | Current selection. |
+## Events
+### Outbound
+```javascript
+// Listen for changes
+root.addEventListener("toggle-group:change", (e) => {
+  console.log(e.detail.value); // string[]
+});
+```
+### Inbound
+```javascript
+// Set selection from outside
+root.dispatchEvent(new CustomEvent("toggle-group:set", {
+  detail: { value: "bold" }
+}));
+// Or with array
+root.dispatchEvent(new CustomEvent("toggle-group:set", {
+  detail: ["bold", "italic"]
+}));
+```
+## Keyboard Navigation
+| Key | Action |
+|-----|--------|
+| `ArrowRight` / `ArrowDown` | Move to next item (based on orientation) |
+| `ArrowLeft` / `ArrowUp` | Move to previous item (based on orientation) |
+| `Home` | Move to first item |
+| `End` | Move to last item |
+| `Enter` / `Space` | Toggle current item |
+## Styling
+```css
+/* Style pressed items */
+[data-slot="toggle-group-item"][data-state="on"] {
+  background: #333;
+  color: white;
+}
+/* Style disabled items */
+[data-slot="toggle-group-item"][aria-disabled="true"] {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```
+## Accessibility
+- Root has `role="group"`
+- Items have `aria-pressed` attribute
+- Disabled items have `aria-disabled="true"` and native `disabled`
+- Supports roving tabindex for keyboard navigation
+- Add `aria-label` or `aria-labelledby` to root for context

package/dist/index.cjs ADDED Viewed

@@ -0,0 +1 @@

+ const e=(e,t)=>[...e.querySelectorAll(`[data-slot="${t}"]`)],t=(e,t)=>[...e.querySelectorAll(`[data-slot="${t}"]`)],n=new WeakMap;function r(e,t,r){if(typeof process<`u`&&process.env?.NODE_ENV===`production`)return;let i=n.get(e);i||(i=new Set,n.set(e,i)),!i.has(t)&&(i.add(t),console.warn(`[@data-slot] ${r}`))}function i(e){let t=`data-${e.replace(/([A-Z])/g,`-$1`).toLowerCase()}`,n=`data-${e}`;return t===n?[t]:[t,n]}function a(e,t){for(let n of i(t))if(e.hasAttribute(n))return e.getAttribute(n);return null}function o(e,t){return i(t).some(t=>e.hasAttribute(t))}const s=new Set([``,`true`,`1`,`yes`]),c=new Set([`false`,`0`,`no`]);function l(e,t){if(!o(e,t))return;let n=a(e,t);if(n===null)return;let i=n.toLowerCase();if(s.has(i))return!0;if(c.has(i))return!1;r(e,t,`Invalid boolean value "${n}" for data-${t}. Expected: true/false/1/0/yes/no or empty.`)}function u(e,t){if(o(e,t))return a(e,t)??void 0}function d(e,t,n){let i=a(e,t);if(i!==null){if(n.includes(i))return i;r(e,t,`Invalid value "${i}" for data-${t}. Expected one of: ${n.join(`, `)}.`)}}let f=0;const p=(e,t)=>e.id||=`${t}-${++f}`,m=(e,t,n)=>{n===null?e.removeAttribute(`aria-${t}`):e.setAttribute(`aria-${t}`,String(n))};function h(e,t,n,r){return e.addEventListener(t,n,r),()=>e.removeEventListener(t,n,r)}const g=(e,t,n)=>e.dispatchEvent(new CustomEvent(t,{bubbles:!0,detail:n})),_=[`horizontal`,`vertical`];function v(t,n={}){let r=e(t,`toggle-group-item`);if(r.length===0)throw Error(`ToggleGroup requires at least one toggle-group-item`);let i=n.multiple??l(t,`multiple`)??!1,a=n.orientation??d(t,`orientation`,_)??`horizontal`,o=n.loop??l(t,`loop`)??!0,s=n.disabled??l(t,`disabled`)??!1,c=n.onValueChange,f=()=>{if(n.defaultValue!==void 0)return Array.isArray(n.defaultValue)?n.defaultValue:n.defaultValue.split(/\s+/).filter(Boolean);let e=u(t,`defaultValue`);return e?e.split(/\s+/).filter(Boolean):[]},v=f(),b=[],x=new Map,S=new Map,C=[];for(let e of r){let t=(e.dataset.value||``).trim();if(!t){C.push(e);continue}let n=e.hasAttribute(`disabled`)||e.hasAttribute(`data-disabled`)||e.getAttribute(`aria-disabled`)===`true`,r={el:e,value:t,disabled:n};b.push(r),x.set(t,r),S.set(e,r)}for(let e of C)e.tabIndex=-1,e.setAttribute(`aria-disabled`,`true`);if(b.length===0)throw Error(`ToggleGroup requires at least one toggle-group-item with a data-value attribute`);let w=new Set;for(let e of v)if(x.has(e)&&(w.add(e),!i))break;let T=[],E=()=>t.hasAttribute(`disabled`)||t.hasAttribute(`data-disabled`)||t.getAttribute(`aria-disabled`)===`true`,D=e=>e.el.hasAttribute(`disabled`)||e.el.hasAttribute(`data-disabled`)||e.el.getAttribute(`aria-disabled`)===`true`,O=()=>b.filter(e=>!D(e));t.setAttribute(`role`,`group`),s&&t.setAttribute(`aria-disabled`,`true`),a===`vertical`&&m(t,`orientation`,`vertical`),i&&(t.dataset.multiple=``);for(let e of b){let{el:t,disabled:n}=e;p(t,`toggle-group-item`),t.tagName===`BUTTON`&&!t.hasAttribute(`type`)&&(t.type=`button`),n&&(t.setAttribute(`aria-disabled`,`true`),t.tagName===`BUTTON`&&(t.disabled=!0))}let k=(e,n=!1)=>{let r=!n&&(e.size!==w.size||[...e].some(e=>!w.has(e)));w=e;for(let e of b){let t=w.has(e.value);m(e.el,`pressed`,t),e.el.dataset.state=t?`on`:`off`}A();let i=[...w];t.setAttribute(`data-value`,i.join(` `)),r&&(g(t,`toggle-group:change`,{value:i}),c?.(i))},A=()=>{let e=O(),t;for(let n of e)if(w.has(n.value)){t=n;break}!t&&e.length>0&&(t=e[0]);for(let e of b)e.el.tabIndex=e===t?0:-1};k(w,!0);let j=e=>{let t=new Set(w);i?t.has(e)?t.delete(e):t.add(e):t.has(e)?t.clear():(t.clear(),t.add(e)),k(t)},M=e=>{let t=Array.isArray(e)?e:e.split(/\s+/).filter(Boolean),n=new Set;for(let e of t)if(x.has(e)&&(n.add(e),!i))break;k(n)};T.push(h(t,`click`,e=>{if(E())return;let t=e.target.closest?.(`[data-slot="toggle-group-item"]`);if(!t)return;let n=S.get(t);!n||D(n)||j(n.value)}));let N=a===`horizontal`,P=N?`ArrowLeft`:`ArrowUp`,F=N?`ArrowRight`:`ArrowDown`;return T.push(h(t,`keydown`,e=>{if(E())return;let t=e.target.closest?.(`[data-slot="toggle-group-item"]`);if(!t)return;let n=S.get(t);if(!n)return;if(e.key===`Enter`||e.key===` `){D(n)&&e.preventDefault();return}let r=O();if(r.length===0)return;let i=r.findIndex(e=>e.el===t);i===-1&&(i=0);let a=i;switch(e.key){case P:a=i-1,a<0&&(a=o?r.length-1:0);break;case F:a=i+1,a>=r.length&&(a=o?0:r.length-1);break;case`Home`:a=0;break;case`End`:a=r.length-1;break;default:return}e.preventDefault();let s=r[a];if(s){for(let e of b)e.el.tabIndex=e===s?0:-1;s.el.focus()}})),T.push(h(t,`toggle-group:set`,e=>{if(E())return;let t=e,n=t.detail,r;if(typeof n==`string`)r=n;else if(Array.isArray(n))r=n;else if(n&&typeof n==`object`&&`value`in n)r=n.value;else return;M(r)})),{setValue:e=>M(e),toggle:e=>j(e),get value(){return[...w]},destroy:()=>{T.forEach(e=>e()),T.length=0,y.delete(t)}}}const y=new WeakSet;function b(e=document){let n=[];for(let r of t(e,`toggle-group`)){if(y.has(r))continue;y.add(r),n.push(v(r))}return n}exports.create=b,exports.createToggleGroup=v;

package/dist/index.d.cts ADDED Viewed

@@ -0,0 +1,60 @@
+//#region src/index.d.ts
+interface ToggleGroupOptions {
+  /** Initial selected value(s) - string for single, string[] for multiple */
+  defaultValue?: string | string[];
+  /** Allow multiple selections (default: false) */
+  multiple?: boolean;
+  /** Orientation for keyboard navigation */
+  orientation?: "horizontal" | "vertical";
+  /** Wrap keyboard focus at ends (default: true) */
+  loop?: boolean;
+  /** Disabled state for entire group */
+  disabled?: boolean;
+  /** Callback when value changes */
+  onValueChange?: (value: string[]) => void;
+}
+interface ToggleGroupController {
+  /** Set value(s) programmatically */
+  setValue(value: string | string[]): void;
+  /** Toggle a specific item */
+  toggle(value: string): void;
+  /** Current selected value(s) */
+  readonly value: string[];
+  /** Cleanup all event listeners */
+  destroy(): void;
+}
+/**
+ * Create a toggle-group controller for a root element
+ *
+ * ## Events
+ * - **Outbound** `toggle-group:change` (on root): Fires when selection changes.
+ *   `event.detail: { value: string[] }`
+ * - **Inbound** `toggle-group:set` (on root): Set selection programmatically.
+ *   `event.detail: { value: string | string[] } | string | string[]`
+ *
+ * @example
+ * ```js
+ * // Listen for changes
+ * root.addEventListener("toggle-group:change", (e) => console.log(e.detail.value));
+ * // Set selection from outside
+ * root.dispatchEvent(new CustomEvent("toggle-group:set", { detail: { value: "bold" } }));
+ * root.dispatchEvent(new CustomEvent("toggle-group:set", { detail: ["bold", "italic"] }));
+ * ```
+ *
+ * Expected markup:
+ * ```html
+ * <div data-slot="toggle-group" data-default-value="center">
+ *   <button data-slot="toggle-group-item" data-value="left">Left</button>
+ *   <button data-slot="toggle-group-item" data-value="center">Center</button>
+ *   <button data-slot="toggle-group-item" data-value="right">Right</button>
+ * </div>
+ * ```
+ */
+declare function createToggleGroup(root: Element, options?: ToggleGroupOptions): ToggleGroupController;
+/**
+ * Find and bind all toggle-group instances in a scope
+ * Returns array of controllers for programmatic access
+ */
+declare function create(scope?: ParentNode): ToggleGroupController[];
+//#endregion
+export { ToggleGroupController, ToggleGroupOptions, create, createToggleGroup };

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,60 @@
+//#region src/index.d.ts
+interface ToggleGroupOptions {
+  /** Initial selected value(s) - string for single, string[] for multiple */
+  defaultValue?: string | string[];
+  /** Allow multiple selections (default: false) */
+  multiple?: boolean;
+  /** Orientation for keyboard navigation */
+  orientation?: "horizontal" | "vertical";
+  /** Wrap keyboard focus at ends (default: true) */
+  loop?: boolean;
+  /** Disabled state for entire group */
+  disabled?: boolean;
+  /** Callback when value changes */
+  onValueChange?: (value: string[]) => void;
+}
+interface ToggleGroupController {
+  /** Set value(s) programmatically */
+  setValue(value: string | string[]): void;
+  /** Toggle a specific item */
+  toggle(value: string): void;
+  /** Current selected value(s) */
+  readonly value: string[];
+  /** Cleanup all event listeners */
+  destroy(): void;
+}
+/**
+ * Create a toggle-group controller for a root element
+ *
+ * ## Events
+ * - **Outbound** `toggle-group:change` (on root): Fires when selection changes.
+ *   `event.detail: { value: string[] }`
+ * - **Inbound** `toggle-group:set` (on root): Set selection programmatically.
+ *   `event.detail: { value: string | string[] } | string | string[]`
+ *
+ * @example
+ * ```js
+ * // Listen for changes
+ * root.addEventListener("toggle-group:change", (e) => console.log(e.detail.value));
+ * // Set selection from outside
+ * root.dispatchEvent(new CustomEvent("toggle-group:set", { detail: { value: "bold" } }));
+ * root.dispatchEvent(new CustomEvent("toggle-group:set", { detail: ["bold", "italic"] }));
+ * ```
+ *
+ * Expected markup:
+ * ```html
+ * <div data-slot="toggle-group" data-default-value="center">
+ *   <button data-slot="toggle-group-item" data-value="left">Left</button>
+ *   <button data-slot="toggle-group-item" data-value="center">Center</button>
+ *   <button data-slot="toggle-group-item" data-value="right">Right</button>
+ * </div>
+ * ```
+ */
+declare function createToggleGroup(root: Element, options?: ToggleGroupOptions): ToggleGroupController;
+/**
+ * Find and bind all toggle-group instances in a scope
+ * Returns array of controllers for programmatic access
+ */
+declare function create(scope?: ParentNode): ToggleGroupController[];
+//#endregion
+export { ToggleGroupController, ToggleGroupOptions, create, createToggleGroup };

package/dist/index.js ADDED Viewed

@@ -0,0 +1 @@

package/package.json ADDED Viewed

@@ -0,0 +1,43 @@
+{
+  "name": "@data-slot/toggle-group",
+  "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-group"
+  },
+  "keywords": [
+    "headless",
+    "ui",
+    "toggle-group",
+    "vanilla",
+    "data-slot"
+  ],
+  "license": "MIT"
+}