shelving 1.249.0 → 1.250.0

package/extract/TypescriptExtractor.d.ts

@@ -12,6 +12,7 @@ import { FileExtractor } from "./FileExtractor.js";
  * - Sets `title` on every `tree-documentation` child — `name()` for functions, `Class.name()` for methods, `Class.name` for properties, bare `name` for other kinds.
  * - Records relational metadata as raw strings for render-time linking: `class` (owning class), `readonly`, `extends` / `implements` (full heritage type text including generic arguments, e.g. `AbstractStore<string>` or `Omit<StringSchemaOptions, "value">`), and `types` (the type names a `type` alias's body references, e.g. `OtherType` in `string | OtherType`).
  * - Records a structured `properties` list for interfaces and object-literal `type` aliases — each member's name, type, optionality, `@default`, and description — so an options-bag parameter can be flattened into its fields at render time.
+ * - Names a destructured (binding-pattern) parameter for the Param column — which has no name of its own — from an explicit `@param`, else its rest element (`...options`), else a type-derived fallback (`props` / `options`). The signature still shows the full `{ … }`.
  * - Pretty-prints object-literal signatures (interfaces and object-literal `type` aliases) as multi-line `{ … }` blocks, one member per line; other type bodies (`string | null`, mapped types, …) are emitted verbatim.
  * - Members declared with the `override` or `declare` modifier are skipped — the base class already documents overrides, and `declare` members are ambient type-only re-declarations rather than new API.
  * - Keys are the raw declared `name` (case-preserving) so case-distinct exports like `Collection` and `COLLECTION` stay separate.

package/extract/TypescriptExtractor.js

@@ -13,6 +13,7 @@ import { extractMarkdownProps } from "./MarkupExtractor.js";
  * - Sets `title` on every `tree-documentation` child — `name()` for functions, `Class.name()` for methods, `Class.name` for properties, bare `name` for other kinds.
  * - Records relational metadata as raw strings for render-time linking: `class` (owning class), `readonly`, `extends` / `implements` (full heritage type text including generic arguments, e.g. `AbstractStore<string>` or `Omit<StringSchemaOptions, "value">`), and `types` (the type names a `type` alias's body references, e.g. `OtherType` in `string | OtherType`).
  * - Records a structured `properties` list for interfaces and object-literal `type` aliases — each member's name, type, optionality, `@default`, and description — so an options-bag parameter can be flattened into its fields at render time.
+ * - Names a destructured (binding-pattern) parameter for the Param column — which has no name of its own — from an explicit `@param`, else its rest element (`...options`), else a type-derived fallback (`props` / `options`). The signature still shows the full `{ … }`.
  * - Pretty-prints object-literal signatures (interfaces and object-literal `type` aliases) as multi-line `{ … }` blocks, one member per line; other type bodies (`string | null`, mapped types, …) are emitted verbatim.
  * - Members declared with the `override` or `declare` modifier are skipped — the base class already documents overrides, and `declare` members are ambient type-only re-declarations rather than new API.
  * - Keys are the raw declared `name` (case-preserving) so case-distinct exports like `Collection` and `COLLECTION` stay separate.
@@ -348,11 +349,23 @@ function _getParams(statement, source, jsDocParams) {
  * - Multiple `@param name` tags for the same parameter each emit a row, so a single parameter can be documented as several typed variants.
  * - A `@param name` with no `{Type}` only supplies the description; the inferred type stands.
  * - `primaryJsDocParams` win over `fallbackJsDocParams` per name (used by constructors: the constructor's own `@param` beats the class-level `@param`).
+ * - A destructured (binding-pattern) param has no name of its own — its display name resolves as an "orphan" `@param` (one not matching any identifier param, in source order), else the rest element (`...options`), else a type-derived fallback (see `_getBindingName`). This keeps the Param column readable (`options`) while the signature still shows the full `{ … }`.
  */
 function _buildParams(parameters, source, primaryJsDocParams, fallbackJsDocParams) {
     const params = [];
+    // Identifier (non-destructured) parameter names — used to spot "orphan" `@param` tags that name a destructured bag.
+    const named = new Set();
+    for (const p of parameters)
+        if (ts.isIdentifier(p.name))
+            named.add(p.name.getText(source));
+    // Top-level `@param` names not matching any identifier parameter, in declared order (constructor's own first, then class-level), de-duplicated — these let an author name a destructured param (`@param options`). Sub-tags (`options.min`) are excluded.
+    const orphans = [];
+    for (const d of [...(primaryJsDocParams ?? []), ...(fallbackJsDocParams ?? [])])
+        if (!d.name.includes(".") && !named.has(d.name) && !orphans.includes(d.name))
+            orphans.push(d.name);
+    let orphan = 0;
     for (const p of parameters) {
-        const name = p.name.getText(source);
+        const name = ts.isIdentifier(p.name) ? p.name.getText(source) : (orphans[orphan++] ?? _getBindingName(p, source));
         const type = p.type?.getText(source);
         const optional = !!p.questionToken || !!p.initializer;
         const def = p.initializer?.getText(source);
@@ -371,6 +384,20 @@ function _buildParams(parameters, source, primaryJsDocParams, fallbackJsDocParam
     }
     return params;
 }
+/**
+ * Derive a display name for a destructured (binding-pattern) parameter, which has no name of its own.
+ * - Prefers the rest element's name when present (`{ min, ...options }` → `options`), since that's already author-supplied and accurate.
+ * - Otherwise falls back to a generic name read from the type — `props` for a `*Props` type (component props), else `options`.
+ * - Callers resolve an explicit `@param` first (see `_buildParams`); this is only the fallback when none is given.
+ */
+function _getBindingName(p, source) {
+    const { name } = p;
+    if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name))
+        for (const el of name.elements)
+            if (ts.isBindingElement(el) && el.dotDotDotToken && ts.isIdentifier(el.name))
+                return el.name.text;
+    return p.type?.getText(source).replace(/<.*/s, "").endsWith("Props") ? "props" : "options";
+}
 /**
  * Extract a class's constructor parameters as `params`, mirroring the function shape.
  * - Descriptions are sourced from the constructor's own `@param` first, falling back to the class-level `@param`.

package/markup/MarkupParser.d.ts

@@ -16,7 +16,7 @@ import type { Parser } from "./Parser.js";
 export type MarkupOptions = {
     /**
      * The active list of parsing rules.
-     * @default MARKUP_RULES The default list of markup rules.
+     * @default MARKUP_RULES
      */
     readonly rules?: MarkupRules | undefined;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.249.0",
+	"version": "1.250.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/ui/block/Preformatted.module.css

@@ -46,7 +46,6 @@
 		/* Scrolling */
 		overflow-y: hidden;
 		overflow-x: auto;
-		overscroll-behavior-y: auto;
 		overscroll-behavior-x: none;
 		scroll-behavior: smooth;
 

package/ui/style/Scroll.module.css

@@ -9,7 +9,6 @@
 	.horizontal,
 	.vertical {
 		overflow: hidden;
-		overscroll-behavior: none;
 	}
 }