@frontfactory/readmore 1.2.0 → 1.3.1

package/README.md

@@ -7,10 +7,11 @@
 Lightweight, framework-agnostic plugin to clamp text to N lines (or a fixed pixel height) with an ellipsis and a
 `Read more` / `Read less` toggle button.
 
-- Zero dependencies, ~1 KB
+- Zero dependencies, ~1.3 KB gzipped
 - TypeScript types included
 - CSS-driven clamping via `-webkit-line-clamp` or `max-height`
 - The toggle button is only created when the text actually overflows
+- Accessible by default: `aria-expanded` and `aria-controls` on the toggle button
 
 ## Installation
 
@@ -18,6 +19,9 @@ Lightweight, framework-agnostic plugin to clamp text to N lines (or a fixed pixe
 npm install @frontfactory/readmore
 ```
 
+Requires Node.js `>=20.19` to build from source. The published package runs in any modern browser supporting 
+`ResizeObserver`.
+
 ## Playground
 
 Try it live on StackBlitz — no installation required:
@@ -47,55 +51,85 @@ ReadMore.init('.excerpt', {
 });
 ```
 
+`ReadMore.init()` also accepts a `NodeList` or an array of elements:
+
+```ts
+ReadMore.init(document.querySelectorAll<HTMLElement>('.excerpt'), {
+    lines: 3
+});
+```
+
 Or instantiate against a single element:
 
 ```ts
 const el = document.querySelector<HTMLElement>('#bio');
 
 if (el) new ReadMore(el, {
-    lines: 4
+    lines: 4,
+    onToggle: (expanded) => console.log('expanded:', expanded)
 });
 ```
 
 ## Options
 
-| Option          | Type     | Default          | Description                                                        |
-|-----------------|----------|------------------|--------------------------------------------------------------------|
-| `lines`         | `number` | `3`              | Number of lines to clamp to. Ignored if `height` is set.           |
-| `height`        | `number` | —                | Max height in pixels. Takes precedence over `lines` when provided. |
-| `moreText`      | `string` | `'Read more'`    | Label of the button when the text is collapsed.                    |
-| `lessText`      | `string` | `'Read less'`    | Label of the button when the text is expanded.                     |
-| `buttonClass`   | `string` | `'readmore-btn'` | Class applied to the toggle button.                                |
-| `expandedClass` | `string` | `'is-expanded'`  | Class applied to the target element while expanded.                |
-| `openingClass`  | `string` | `'is-opening'`   | Transient class applied while expanding, removed after transition. |
-| `closingClass`  | `string` | `'is-closing'`   | Transient class applied while collapsing, removed after transition.|
+| Option          | Type                          | Default          | Description                                                         |
+|-----------------|-------------------------------|------------------|---------------------------------------------------------------------|
+| `lines`         | `number`                      | `3`              | Number of lines to clamp to (min `1`). Ignored if `height` is set.  |
+| `height`        | `number`                      | —                | Max height in pixels (min `1`). Takes precedence over `lines`.      |
+| `moreText`      | `string`                      | `'Read more'`    | Label of the button when the text is collapsed.                     |
+| `lessText`      | `string`                      | `'Read less'`    | Label of the button when the text is expanded.                      |
+| `buttonClass`   | `string`                      | `'readmore-btn'` | Class applied to the toggle button.                                 |
+| `expandedClass` | `string`                      | `'is-expanded'`  | Class applied to the target element while expanded.                 |
+| `openingClass`  | `string`                      | `'is-opening'`   | Transient class applied while expanding, removed after transition.  |
+| `closingClass`  | `string`                      | `'is-closing'`   | Transient class applied while collapsing, removed after transition. |
+| `onToggle`      | `(expanded: boolean) => void` | —                | Callback fired after each toggle with the current `expanded` state. |
 
 ## API
 
 ```ts
 const instance = new ReadMore(element, options);
 
+instance.el;            // the target element
+instance.options;       // resolved options
 instance.toggle();      // expand / collapse programmatically
 instance.expanded;      // boolean getter
-instance.destroy();     // remove button, classes and listeners
+instance.destroy();     // remove button, classes, listeners and generated id
 
-ReadMore.init(selector, options); // returns ReadMore[]
+ReadMore.init(target, options);   // target: selector | NodeList | HTMLElement[] — returns ReadMore[]
+ReadMore.getInstance(element);    // returns the ReadMore bound to an element, or undefined
 ```
 
+### Errors
+
+The constructor throws instead of failing silently:
+
+| Error        | When                                                                          |
+|--------------|-------------------------------------------------------------------------------|
+| `TypeError`  | `element` is not an `HTMLElement`.                                            |
+| `Error`      | The element is already initialized — call `destroy()` before re-initializing. |
+| `RangeError` | `lines` is lower than `1`, or `height` is lower than or equal to `0`.         |
+
+## Accessibility
+
+When the button is mounted, it gets `aria-expanded` (kept in sync on every toggle) and `aria-controls`
+pointing to the target element. If the element has no `id`, a unique one (`readmore-1`, `readmore-2`, …)
+is generated and removed again on `destroy()`; an existing `id` is always preserved.
+
 ## How it works
 
 The plugin sets a CSS custom property on the target element and toggles `.readmore-clamp`. In **lines mode** (default),
 it sets `--readmore-lines` and the bundled stylesheet applies `-webkit-line-clamp`, producing an ellipsis at the end of
 the last visible line. In **height mode** (`height` option), it sets `--readmore-height` and applies `max-height` via
 the `.readmore-clamp--height` modifier class instead. The toggle button is mounted right after the element only when the
-content actually overflows, and unmounted again on resize if the text ends up fitting.
+content actually overflows; a `ResizeObserver` watches the element and unmounts the button again if the text ends up
+fitting (or mounts it later if it starts overflowing).
 
 ### Transient classes for animations
 
 In addition to `expandedClass` (which stays applied for the entire expanded state), the plugin applies short-lived
-`openingClass` and `closingClass` markers on the target element at the moment of expand and collapse respectively.
-Each is added when the toggle starts and removed automatically once the CSS transition on the element ends — or on the
-next tick if no transition is declared. Use them as hooks to drive enter/leave animations:
+`openingClass` and `closingClass` markers on the target element at the moment of expand and collapse respectively. Each
+is added when the toggle starts and removed automatically once the CSS transition on the element ends — or on the next
+tick if no transition is declared. Use them as hooks to drive enter/leave animations:
 
 ```css
 .is-opening { 

package/dist/readmore.d.ts

@@ -1,25 +1,128 @@
+/**
+ * Options accepted by {@link ReadMore}. Every field is optional.
+ */
 export interface ReadMoreOptions {
+    /**
+     * Number of lines to clamp to. Ignored when {@link ReadMoreOptions.height} is set.
+     *
+     * @defaultValue 3
+     * @throws RangeError - if lower than 1.
+     */
     lines?: number;
+    /**
+     * Max height in pixels. Takes precedence over {@link ReadMoreOptions.lines}
+     * and clamps with `max-height` instead of `-webkit-line-clamp`.
+     *
+     * @throws RangeError - if lower than or equal to 0.
+     */
     height?: number;
+    /**
+     * Label of the toggle button while the text is collapsed.
+     *
+     * @defaultValue 'Read more'
+     */
     moreText?: string;
+    /**
+     * Label of the toggle button while the text is expanded.
+     *
+     * @defaultValue 'Read less'
+     */
     lessText?: string;
+    /**
+     * Class applied to the toggle button.
+     *
+     * @defaultValue 'readmore-btn'
+     */
     buttonClass?: string;
+    /**
+     * Class applied to the target element for the whole expanded state.
+     *
+     * @defaultValue 'is-expanded'
+     */
     expandedClass?: string;
+    /**
+     * Transient class applied when expanding, removed once the CSS transition
+     * on the element ends — or on the next tick if no transition is declared.
+     *
+     * @defaultValue 'is-opening'
+     */
     openingClass?: string;
+    /**
+     * Transient class applied when collapsing, removed once the CSS transition
+     * on the element ends — or on the next tick if no transition is declared.
+     *
+     * @defaultValue 'is-closing'
+     */
     closingClass?: string;
+    /**
+     * Called after each toggle with the resulting state.
+     *
+     * @param expanded - `true` once expanded, `false` once collapsed.
+     */
+    onToggle?: (expanded: boolean) => void;
 }
-type ResolvedOptions = Required<Omit<ReadMoreOptions, 'height'>> & {
+/**
+ * {@link ReadMoreOptions} merged with the defaults, as exposed on
+ * {@link ReadMore.options}.
+ */
+export type ResolvedOptions = Required<Omit<ReadMoreOptions, 'height' | 'onToggle'>> & {
     height?: number;
+    onToggle?: (expanded: boolean) => void;
 };
+/**
+ * Clamps an element to a number of lines (or a fixed height) and mounts a
+ * `Read more` / `Read less` button right after it, but only while the content
+ * actually overflows.
+ *
+ * @example
+ * ```ts
+ * import { ReadMore } from '@frontfactory/readmore';
+ * import '@frontfactory/readmore/style.css';
+ *
+ * ReadMore.init('.excerpt', { lines: 3 });
+ * ```
+ */
 export declare class ReadMore {
     #private;
+    /** The clamped element. */
     readonly el: HTMLElement;
+    /** The options this instance was built with, merged with the defaults. */
     readonly options: ResolvedOptions;
+    /**
+     * @param element - The element to clamp.
+     * @param options - See {@link ReadMoreOptions}.
+     * @throws TypeError - if `element` is not an `HTMLElement`.
+     * @throws Error - if `element` is already initialized; call
+     * {@link ReadMore.destroy} first.
+     * @throws RangeError - if `lines` is lower than 1, or `height` lower than
+     * or equal to 0.
+     */
     constructor(element: HTMLElement, options?: ReadMoreOptions);
+    /**
+     * Instantiates {@link ReadMore} on every matching element.
+     *
+     * @param target - A CSS selector, a `NodeList` or an array of elements.
+     * @param options - See {@link ReadMoreOptions}.
+     * @returns One instance per element, in document order.
+     */
     static init(target: string | NodeListOf<HTMLElement> | HTMLElement[], options?: ReadMoreOptions): ReadMore[];
+    /** Whether the text is currently expanded. */
     get expanded(): boolean;
+    /**
+     * Expands or collapses the text, updating the button label, the
+     * `aria-expanded` attribute and the state classes, then calls
+     * {@link ReadMoreOptions.onToggle}.
+     */
     toggle(): void;
+    /**
+     * @param element - An element possibly initialized by this plugin.
+     * @returns The instance bound to it, or `undefined`.
+     */
     static getInstance(element: HTMLElement): ReadMore | undefined;
+    /**
+     * Restores the element: removes the button, the classes, the CSS custom
+     * properties, the listeners and the generated `id`. The element can then be
+     * initialized again.
+     */
     destroy(): void;
 }
-export {};

package/dist/readmore.js

@@ -19,10 +19,12 @@ var e = "readmore-clamp", t = "readmore-clamp--height", n = /* @__PURE__ */ new
 	constructor(e, t = {}) {
 		if (!(e instanceof HTMLElement)) throw TypeError("ReadMore: an HTMLElement is required.");
 		if (n.has(e)) throw Error("ReadMore: element is already initialized. Call destroy() first.");
-		this.el = e, this.options = {
+		if (this.el = e, this.options = {
 			...i,
 			...t
-		}, this.#r = new ResizeObserver(() => this.#c()), n.set(e, this), this.#o();
+		}, this.options.height != null && this.options.height <= 0) throw RangeError("ReadMore: height must be greater than 0.");
+		if (this.options.lines < 1) throw RangeError("ReadMore: lines must be at least 1.");
+		this.#r = new ResizeObserver(() => this.#c()), n.set(e, this), this.#o();
 	}
 	static init(e, t) {
 		let n = typeof e == "string" ? document.querySelectorAll(e) : e;
@@ -34,7 +36,7 @@ var e = "readmore-clamp", t = "readmore-clamp--height", n = /* @__PURE__ */ new
 	toggle() {
 		this.#t = !this.#t, this.el.classList.toggle(e, !this.#t), this.options.height != null && this.el.classList.toggle(t, !this.#t), this.el.classList.toggle(this.options.expandedClass, this.#t), this.#e && (this.#e.textContent = this.#t ? this.options.lessText : this.options.moreText, this.#e.setAttribute("aria-expanded", String(this.#t)));
 		let n = this.#t ? this.options.openingClass : this.options.closingClass, r = this.#t ? this.options.closingClass : this.options.openingClass;
-		this.el.classList.remove(r), this.#l(n), this.#t || this.#c();
+		this.el.classList.remove(r), this.#l(n), this.#t || this.#c(), this.options.onToggle?.(this.#t);
 	}
 	static getInstance(e) {
 		return n.get(e);

package/package.json

@@ -1,28 +1,31 @@
 {
     "name": "@frontfactory/readmore",
-    "version": "1.2.0",
-    "description": "Lightweight plugin to clamp text to N lines with ellipsis and a read more action.",
+    "version": "1.3.1",
+    "description": "Zero-dependency plugin to truncate text to N lines or a fixed height, with an ellipsis and an accessible read more / read less toggle.",
     "type": "module",
     "scripts": {
         "dev": "vite",
+        "lint:js": "eslint --fix .",
         "build": "vite build",
         "preview": "vite preview",
         "typecheck": "tsc --noEmit",
         "test": "vitest run",
         "test:watch": "vitest",
         "test:coverage": "vitest run --coverage",
-        "prepare": "husky && npm run build",
+        "prepare": "husky",
+        "prepack": "npm run build",
         "release": "semantic-release"
     },
     "engines": {
-        "node": ">=20.19"
+        "node": ">=20"
     },
     "main": "./dist/readmore.js",
     "types": "./dist/readmore.d.ts",
     "exports": {
         ".": {
             "types": "./dist/readmore.d.ts",
-            "import": "./dist/readmore.js"
+            "import": "./dist/readmore.js",
+            "default": "./dist/readmore.js"
         },
         "./style.css": "./dist/readmore.css",
         "./package.json": "./package.json"
@@ -30,30 +33,40 @@
     "devDependencies": {
         "@commitlint/cli": "^20.5.3",
         "@commitlint/config-conventional": "^20.5.3",
+        "@front-factory/eslint-config": "^2.4.2",
         "@semantic-release/changelog": "^6.0.3",
         "@semantic-release/git": "^10.0.1",
         "@semantic-release/github": "^12.0.6",
         "@vitest/coverage-v8": "^4.1.5",
         "conventional-changelog-conventionalcommits": "^9.3.1",
+        "eslint": "^10.3.0",
         "husky": "^9.1.7",
         "jsdom": "^29.1.1",
         "lightningcss": "^1.32.0",
         "semantic-release": "^25.0.3",
         "typescript": "^5.4.0",
+        "typescript-eslint": "^8.59.2",
         "vite": "^8.0.11",
         "vite-plugin-dts": "^5.0.0",
         "vite-plugin-static-copy": "^4.1.0",
         "vitest": "^4.1.5"
     },
-    "files": [
-        "dist"
-    ],
     "keywords": [
         "readmore",
+        "read-more",
+        "show-more",
+        "truncate",
+        "text-truncate",
+        "line-clamp",
+        "clamp",
+        "ellipsis",
         "expand",
         "collapse",
-        "front-end"
+        "typescript",
+        "vanilla-js",
+        "a11y"
     ],
+    "author": "Front Factory",
     "license": "MIT",
     "homepage": "https://github.com/front-factory/readmore",
     "bugs": {
@@ -63,6 +76,12 @@
         "type": "git",
         "url": "git+https://github.com/front-factory/readmore.git"
     },
+    "sideEffects": [
+        "**/*.css"
+    ],
+    "files": [
+        "dist"
+    ],
     "publishConfig": {
         "access": "public",
         "provenance": true