@data-slot/core 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# @data-slot/core
+
+Shared utilities for data-slot headless UI components.
+
+## Installation
+
+```bash
+npm install @data-slot/core
+```
+
+## API
+
+### DOM Utilities
+
+#### `getPart(root, slot)`
+
+Query a single part/slot within a component root.
+
+```typescript
+const trigger = getPart<HTMLButtonElement>(root, "dialog-trigger");
+```
+
+#### `getParts(root, slot)`
+
+Query all parts/slots within a component root.
+
+```typescript
+const items = getParts<HTMLElement>(root, "accordion-item");
+```
+
+#### `getRoots(scope, slot)`
+
+Find all component roots within a scope by data-slot value.
+
+```typescript
+const dialogs = getRoots(document, "dialog");
+```
+
+### ARIA Utilities
+
+#### `ensureId(element, prefix)`
+
+Ensure an element has an id, generating one if needed.
+
+```typescript
+const id = ensureId(content, "dialog-content");
+// Returns existing id or generates "dialog-content-1"
+```
+
+#### `setAria(element, name, value)`
+
+Set or remove an ARIA attribute. Boolean values are converted to strings.
+
+```typescript
+setAria(trigger, "expanded", true);  // aria-expanded="true"
+setAria(trigger, "expanded", null);  // removes aria-expanded
+```
+
+#### `linkLabelledBy(content, title, description)`
+
+Link content element to its label and description via ARIA.
+
+```typescript
+linkLabelledBy(dialogContent, titleElement, descriptionElement);
+// Sets aria-labelledby and aria-describedby
+```
+
+### Event Utilities
+
+#### `on(element, type, handler, options?)`
+
+Add an event listener and return a cleanup function.
+
+```typescript
+const cleanup = on(button, "click", () => console.log("clicked"));
+// Later: cleanup() to remove listener
+```
+
+#### `emit(element, name, detail?)`
+
+Dispatch a custom event with optional detail.
+
+```typescript
+emit(root, "tabs:change", { value: "tab-2" });
+```
+
+#### `composeHandlers(...handlers)`
+
+Compose multiple event handlers into one. Stops if `event.defaultPrevented`.
+
+```typescript
+const handler = composeHandlers(onClickProp, internalHandler);
+```
+
+## Usage in Components
+
+This package is used internally by all `@data-slot/*` component packages. You typically don't need to import it directly unless building custom components.
+
+```typescript
+import { getPart, setAria, on } from "@data-slot/core";
+
+function createCustomComponent(root: Element) {
+  const trigger = getPart(root, "custom-trigger");
+  const content = getPart(root, "custom-content");
+  
+  const cleanup = on(trigger, "click", () => {
+    const isOpen = content.hidden;
+    content.hidden = !isOpen;
+    setAria(trigger, "expanded", isOpen);
+  });
+  
+  return { destroy: cleanup };
+}
+```
+
+## License
+
+MIT
+

package/dist/index.cjs

@@ -0,0 +1 @@
+const e=(e,t)=>e.querySelector(`[data-slot="${t}"]`),t=(e,t)=>[...e.querySelectorAll(`[data-slot="${t}"]`)],n=(e,t)=>[...e.querySelectorAll(`[data-slot="${t}"]`)];let r=0;const i=(e,t)=>e.id||=`${t}-${++r}`,a=(e,t,n)=>{n===null?e.removeAttribute(`aria-${t}`):e.setAttribute(`aria-${t}`,String(n))},o=(e,t,n)=>{t&&e.setAttribute(`aria-labelledby`,i(t,`title`)),n&&e.setAttribute(`aria-describedby`,i(n,`desc`))},s=(e,t,n,r)=>(e.addEventListener(t,n,r),()=>e.removeEventListener(t,n,r)),c=(e,t,n)=>e.dispatchEvent(new CustomEvent(t,{bubbles:!0,detail:n})),l=(...e)=>t=>{for(let n of e){if(t.defaultPrevented)break;n?.(t)}};exports.composeHandlers=l,exports.emit=c,exports.ensureId=i,exports.getPart=e,exports.getParts=t,exports.getRoots=n,exports.linkLabelledBy=o,exports.on=s,exports.setAria=a;

package/dist/index.d.cts

@@ -0,0 +1,45 @@
+//#region src/parts.d.ts
+/**
+ * Query a single part/slot within a component root
+ */
+declare const getPart: <T extends Element = Element>(root: Element, slot: string) => T | null;
+/**
+ * Query all parts/slots within a component root
+ */
+declare const getParts: <T extends Element = Element>(root: Element, slot: string) => T[];
+/**
+ * Find all component roots within a scope by data-slot value
+ */
+declare const getRoots: <T extends Element = Element>(scope: ParentNode, slot: string) => T[];
+//#endregion
+//#region src/aria.d.ts
+/**
+ * Ensure an element has an id, generating one if needed
+ */
+declare const ensureId: (el: Element, prefix: string) => string;
+/**
+ * Set or remove an ARIA attribute
+ * Note: boolean values are converted to strings, use null to remove
+ */
+declare const setAria: (el: Element, name: string, value: string | boolean | null) => void;
+/**
+ * Link content element to its label and description via ARIA
+ */
+declare const linkLabelledBy: (content: Element, title?: Element | null, description?: Element | null) => void;
+//#endregion
+//#region src/events.d.ts
+/**
+ * Add an event listener and return a cleanup function
+ */
+declare const on: <K extends keyof HTMLElementEventMap>(el: EventTarget, type: K, fn: (e: HTMLElementEventMap[K]) => void, opts?: AddEventListenerOptions) => (() => void);
+/**
+ * Dispatch a custom event with optional detail
+ */
+declare const emit: <T = unknown>(el: Element, name: string, detail?: T) => boolean;
+/**
+ * Compose multiple event handlers into one
+ * Handlers are called in order, stops if event.defaultPrevented
+ */
+declare const composeHandlers: <E extends Event>(...handlers: Array<((e: E) => void) | undefined>) => ((e: E) => void);
+//#endregion
+export { composeHandlers, emit, ensureId, getPart, getParts, getRoots, linkLabelledBy, on, setAria };

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+//#region src/parts.d.ts
+/**
+ * Query a single part/slot within a component root
+ */
+declare const getPart: <T extends Element = Element>(root: Element, slot: string) => T | null;
+/**
+ * Query all parts/slots within a component root
+ */
+declare const getParts: <T extends Element = Element>(root: Element, slot: string) => T[];
+/**
+ * Find all component roots within a scope by data-slot value
+ */
+declare const getRoots: <T extends Element = Element>(scope: ParentNode, slot: string) => T[];
+//#endregion
+//#region src/aria.d.ts
+/**
+ * Ensure an element has an id, generating one if needed
+ */
+declare const ensureId: (el: Element, prefix: string) => string;
+/**
+ * Set or remove an ARIA attribute
+ * Note: boolean values are converted to strings, use null to remove
+ */
+declare const setAria: (el: Element, name: string, value: string | boolean | null) => void;
+/**
+ * Link content element to its label and description via ARIA
+ */
+declare const linkLabelledBy: (content: Element, title?: Element | null, description?: Element | null) => void;
+//#endregion
+//#region src/events.d.ts
+/**
+ * Add an event listener and return a cleanup function
+ */
+declare const on: <K extends keyof HTMLElementEventMap>(el: EventTarget, type: K, fn: (e: HTMLElementEventMap[K]) => void, opts?: AddEventListenerOptions) => (() => void);
+/**
+ * Dispatch a custom event with optional detail
+ */
+declare const emit: <T = unknown>(el: Element, name: string, detail?: T) => boolean;
+/**
+ * Compose multiple event handlers into one
+ * Handlers are called in order, stops if event.defaultPrevented
+ */
+declare const composeHandlers: <E extends Event>(...handlers: Array<((e: E) => void) | undefined>) => ((e: E) => void);
+//#endregion
+export { composeHandlers, emit, ensureId, getPart, getParts, getRoots, linkLabelledBy, on, setAria };

package/dist/index.js

@@ -0,0 +1 @@
+const e=(e,t)=>e.querySelector(`[data-slot="${t}"]`),t=(e,t)=>[...e.querySelectorAll(`[data-slot="${t}"]`)],n=(e,t)=>[...e.querySelectorAll(`[data-slot="${t}"]`)];let r=0;const i=(e,t)=>e.id||=`${t}-${++r}`,a=(e,t,n)=>{n===null?e.removeAttribute(`aria-${t}`):e.setAttribute(`aria-${t}`,String(n))},o=(e,t,n)=>{t&&e.setAttribute(`aria-labelledby`,i(t,`title`)),n&&e.setAttribute(`aria-describedby`,i(n,`desc`))},s=(e,t,n,r)=>(e.addEventListener(t,n,r),()=>e.removeEventListener(t,n,r)),c=(e,t,n)=>e.dispatchEvent(new CustomEvent(t,{bubbles:!0,detail:n})),l=(...e)=>t=>{for(let n of e){if(t.defaultPrevented)break;n?.(t)}};export{l as composeHandlers,c as emit,i as ensureId,e as getPart,t as getParts,n as getRoots,o as linkLabelledBy,s as on,a as setAria};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@data-slot/core",
+  "version": "0.1.0",
+  "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"
+  },
+  "keywords": ["headless", "ui", "components", "vanilla", "data-slot"],
+  "license": "MIT"
+}