@diplodoc/tabs-extension 3.9.0 → 3.10.0

package/README.md

@@ -1,6 +1,11 @@
 # Diplodoc tabs extension
 
 [![NPM version](https://img.shields.io/npm/v/@diplodoc/tabs-extension.svg?style=flat)](https://www.npmjs.org/package/@diplodoc/tabs-extension)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_tabs-extension&metric=alert_status)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_tabs-extension)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_tabs-extension&metric=coverage)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_tabs-extension)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_tabs-extension&metric=sqale_rating)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_tabs-extension)
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_tabs-extension&metric=reliability_rating)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_tabs-extension)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_tabs-extension&metric=security_rating)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_tabs-extension)
 
 This is an extension of the Diplodoc platform, which allows adding switchable tabs in the documentation.
 
@@ -73,7 +78,7 @@ Options:
   (Default: `_assets/tabs-extension.css`)<br>
 
 - `bundle` - boolean flag to enable/disable copying of bundled runtime to target directory.<br>
-  Where target directore is `<transformer output option>/<plugin runtime option>`<br>
+  Where target directory is `<transformer output option>/<plugin runtime option>`<br>
   Default: `true`<br>
 
 - `containerClasses` - additional classes which will be added to tab's container node. It allows to customize the tabs view.<br>
@@ -106,10 +111,10 @@ Example:
 {% endlist %}
 ```
 
-Additionally, you can use different render mosed using a contruction
+Additionally, you can use different render modes with:
 
 ```
-{% list tabs <regular | radio | dropdown> %}
+{% list tabs <regular | radio | dropdown | accordion> %}
 
   - Tab 1
 
@@ -245,6 +250,10 @@ export const App: React.FC = () => {
 }
 ```
 
+## Documentation
+
+- **For AI agents** — see [AGENTS.md](AGENTS.md) and the guides in [docs/AGENTS/](docs/AGENTS/) (core concepts, dev infrastructure).
+
 ## For contributors
 
 Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.

package/build/common.d.ts

@@ -1,11 +1,18 @@
+/**
+ * Shared constants, types and globals for the tabs extension.
+ * Used by both the MarkdownIt plugin (compile-time) and the runtime controller (DOM).
+ */
 import { type TabsController } from './runtime/TabsController';
+/** Regex to match the opening `{% list tabs ... %}` tag (optionally backtick-escaped). */
 export declare const TAB_RE: RegExp;
+/** CSS class names for tab structure. */
 export declare const TABS_CLASSNAME = "yfm-tabs";
 export declare const TAB_CLASSNAME = "yfm-tab";
 export declare const TAB_PANEL_CLASSNAME = "yfm-tab-panel";
 export declare const TABS_LIST_CLASSNAME = "yfm-tab-list";
 export declare const ACTIVE_CLASSNAME = "active";
 export declare const TAB_GROUP_CLASSNAME = "yfm-tab-group";
+/** Data attributes used by the runtime to identify groups, keys, variants and active state. */
 export declare const TAB_ACTIVE_KEY = "data-diplodoc-is-active";
 export declare const GROUP_DATA_KEY = "data-diplodoc-group";
 export declare const TAB_DATA_KEY = "data-diplodoc-key";
@@ -14,31 +21,39 @@ export declare const TAB_DATA_ID = "data-diplodoc-id";
 export declare const DEFAULT_TABS_GROUP_PREFIX = "defaultTabsGroup-";
 export declare const ACTIVE_TAB_TEXT = "{selected}";
 export declare const TAB_FORCED_OPEN = "data-diplodoc-forced";
+/** Dropdown variant: container, menu and select element class names. */
 export declare const TABS_DROPDOWN_CLASSNAME = "yfm-tabs-dropdown";
 export declare const TABS_DROPDOWN_MENU_CLASSNAME = "yfm-tabs-dropdown-menu";
 export declare const TABS_DROPDOWN_SELECT = "yfm-tabs-dropdown-select";
+/** Accordion variant. */
 export declare const TABS_ACCORDION_CLASSNAME = "yfm-tabs-accordion";
 export declare const TABS_ACCORDION_CLIENT_HEIGHT = "data-yfm-tabs-accordion-client-heights";
+/** Radio (vertical) variant. */
 export declare const TABS_RADIO_CLASSNAME = "yfm-tabs-vertical";
 export declare const VERTICAL_TAB_CLASSNAME = "yfm-vertical-tab";
 export declare const TAB_DATA_VERTICAL_TAB = "data-diplodoc-vertical-tab";
 export declare const TAB_RADIO_KEY = "data-diplodoc-input";
+/** Available tab block variants (regular horizontal, radio, dropdown, accordion). */
 export declare enum TabsVariants {
     Regular = "regular",
     Radio = "radio",
     Dropdown = "dropdown",
     Accordion = "accordion"
 }
+/** Which variants are enabled in the plugin (others fall back to Regular). */
 export type EnabledVariants = Partial<Record<TabsVariants, boolean>>;
+/** Identifies a tab: group id, tab key (from content), and variant. */
 export interface Tab {
     group?: string;
     key: string;
     variant: TabsVariants;
 }
+/** Payload passed to onSelectTab handlers when a tab is switched. */
 export interface SelectedTabEvent {
     tab: Tab;
     currentTabId?: string;
 }
+/** Symbol under which the global TabsController instance is stored on `window`. */
 export declare const GLOBAL_SYMBOL: unique symbol;
 declare global {
     interface Window {

package/build/plugin/find.d.ts

@@ -1,6 +1,17 @@
+/**
+ * Parsing of `{% list tabs %}` blocks: locate open/close tags, parse props, and extract tab items
+ * from the list tokens between them.
+ */
+import type { RuntimeTab, TabsProps } from './types';
+import type { IDGenerator } from '@diplodoc/utils';
 import Token from 'markdown-it/lib/token';
-import { RuntimeTab, TabsProps } from './types';
-export declare function props(content: string): TabsProps;
+/**
+ * Parse `{% list tabs group=... %}` content into variant and group id.
+ * @param content - Raw tag content after "list tabs"
+ * @param generateID - per-file isolated ID generator used for default group id
+ * @returns Parsed props (variant, group)
+ */
+export declare function props(content: string, generateID: IDGenerator): TabsProps;
 type Result = {
     step: number;
 } | {
@@ -8,6 +19,19 @@ type Result = {
     closeTokenIndex: number;
     extraTokensAfterClose: number;
 };
+/**
+ * Check if tokens at index start a valid `{% list tabs %}` block.
+ * @param tokens - Full token list
+ * @param index - Start index
+ * @returns Either a step to advance, or the block content and close index for replacement
+ */
 export declare function tryToFindTabs(tokens: Token[], index: number): Result;
+/**
+ * Extract tab items (name + tokens) from list tokens between list open and close/endlist.
+ * @param tokens - Full token list
+ * @param idx - Index after list open
+ * @param closeTokenIdx - Index of {% endlist %} paragraph
+ * @returns Array of RuntimeTab
+ */
 export declare function findTabs(tokens: Token[], idx: number, closeTokenIdx: number): RuntimeTab[];
 export {};

package/build/plugin/generate.d.ts

@@ -1,4 +1,13 @@
+import type Token from 'markdown-it/lib/token';
 import type StateCore from 'markdown-it/lib/rules_core/state_core';
-import { RuntimeTab } from './types';
-import { TabsGenerationProps } from './variants/types';
-export declare function generateTabsTokens(tabs: RuntimeTab[], state: StateCore, props: TabsGenerationProps): import("markdown-it/lib/token")[];
+import type { RuntimeTab } from './types';
+import type { TabsGenerationProps } from './variants/types';
+/**
+ * Generate markdown-it tokens for a tabs block based on the chosen variant.
+ * Delegates to the variant-specific generator (regular, radio, dropdown, accordion).
+ * @param tabs - Parsed tab items
+ * @param state - MarkdownIt state
+ * @param props - Generation options (containerClasses, tabsGroup, runId, variant)
+ * @returns Token array for the block
+ */
+export declare function generateTabsTokens(tabs: RuntimeTab[], state: StateCore, props: TabsGenerationProps): Token[];

package/build/plugin/index.d.ts

@@ -1 +1,2 @@
+/** Tabs extension: MarkdownIt plugin that transforms `{% list tabs %}` into tab HTML. */
 export { transform } from './transform';