@dxtmisha/wiki 0.25.1 → 0.39.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dxtmisha/wiki",
   "private": false,
-  "version": "0.25.1",
+  "version": "0.39.1",
   "type": "module",
   "description": "Wiki documentation and storybook utilities for DXT UI design system",
   "keywords": [
@@ -43,7 +43,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "peerDependencies": {
     "@dxtmisha/functional": "*",

package/src/classes/WikiStorybook.ts

@@ -1,12 +1,14 @@
-import { Geo, isObjectNotArray, toCamelCase } from '@dxtmisha/functional'
+import { forEach, Geo, isObjectNotArray, toCamelCase } from '@dxtmisha/functional'
 
 import { WikiStorybookItem } from './WikiStorybookItem'
+import { WikiStorybookProp } from './WikiStorybookProp'
 
 import {
   type StorybookArgs,
   type StorybookArgsToDescription,
   type StorybookArgsToItem,
   type StorybookArgsToList,
+  type StorybookArgsToPossibilities,
   type StorybookComponentsDescription,
   type StorybookComponentsDescriptionItem,
   type StorybookComponentsDescriptionStory,
@@ -63,6 +65,23 @@ export class WikiStorybook {
     return this.initPropsWiki()
   }
 
+  /**
+   * Returns the wiki object for the component
+   *
+   * Возвращает объект wiki для компонента
+   * @return The wiki object for the component/ объект wiki для компонента
+   */
+  getWikiObject(): WikiStorybookProp[] {
+    return forEach(
+      this.getWiki(),
+      (item, name) => {
+        if (item) {
+          return new WikiStorybookProp(name, item)
+        }
+      }
+    ) as WikiStorybookProp[]
+  }
+
   /**
    * Returns the description of the component from the wiki
    *
@@ -73,6 +92,16 @@ export class WikiStorybook {
     return this.toDescriptionText(this.getDescriptionItem()?.description)
   }
 
+  /**
+   * Returns the possibilities of the component from the wiki
+   *
+   * Возвращает возможности компонента из wiki
+   * @return A list of possibilities for the component/ список возможностей для компонента
+   */
+  getPossibilities(): string[] {
+    return this.toPossibilitiesText(this.getDescriptionItem()?.possibilities)
+  }
+
   /**
    * Returns the values of the wiki items
    *
@@ -89,6 +118,28 @@ export class WikiStorybook {
     return values
   }
 
+  /**
+   * Returns the filtered values of the wiki items
+   *
+   * Возвращает отфильтрованные значения элементов wiki
+   * @return A list of objects containing the filtered values of the wiki items/
+   * список объектов, содержащих отфильтрованные значения элементов wiki
+   */
+  getFilteredValues(): Record<string, any> {
+    const values: Record<string, any> = {}
+
+    forEach(
+      this.getValues(),
+      (value, key) => {
+        if (value !== undefined) {
+          values[key] = value
+        }
+      }
+    )
+
+    return values
+  }
+
   /**
    * Returns a Storybook item by its ID
    *
@@ -120,6 +171,24 @@ export class WikiStorybook {
     )
   }
 
+  /**
+   * Returns the AI render of the component
+   *
+   * Возвращает AI рендер компонента
+   */
+  getAiRender(): string | undefined {
+    return this.getDescriptionItem()?.ai?.render
+  }
+
+  /**
+   * Returns the AI description of the component
+   *
+   * Возвращает AI описание компонента
+   */
+  getAiDescription(): string | undefined {
+    return this.getDescriptionItem()?.ai?.description
+  }
+
   /**
    * Returns a wiki item by its name
    *
@@ -196,6 +265,28 @@ export class WikiStorybook {
     return ''
   }
 
+  /**
+   * Converts the possibilities to text format
+   *
+   * Преобразует возможности в текстовый формат
+   * @param possibilities - The possibilities to convert/ возможности для преобразования
+   */
+  private toPossibilitiesText(possibilities?: StorybookArgsToPossibilities): string[] {
+    if (possibilities) {
+      const language = Geo.getLanguage()
+
+      if (isObjectNotArray(possibilities)) {
+        return possibilities?.[language]
+          ?? Object.values(possibilities)?.[0]
+          ?? []
+      }
+
+      return possibilities
+    }
+
+    return []
+  }
+
   /**
    * Initializes the list of wiki items for the component
    *

package/src/classes/WikiStorybookItem.ts

@@ -26,6 +26,15 @@ export class WikiStorybookItem {
   ) {
   }
 
+  /**
+   * Checks if the item is a demo item.
+   *
+   * Проверяет, является ли элемент демонстрационным.
+   */
+  isDemo(): boolean {
+    return this.item.isDemo === true
+  }
+
   /**
    * Returns the name of the item in the wiki
    *
@@ -86,6 +95,8 @@ export class WikiStorybookItem {
         return 9000
       case StorybookCategory.option:
         return 9100
+      case StorybookCategory.attributes:
+        return 9700
       case StorybookCategory.text:
         return 9800
       case StorybookCategory.aria:
@@ -117,6 +128,40 @@ export class WikiStorybookItem {
     }
   }
 
+  /**
+   * Returns the demo property if the item is a demo item.
+   *
+   * Возвращает свойство demo, если элемент является демонстрационным.
+   */
+  private getDemo(): { isDemo?: boolean, demo?: any, demoOptions?: Record<string, any> } {
+    if (this.isDemo()) {
+      return {
+        isDemo: true,
+        demo: this.getDemoValue(),
+        demoOptions: this.item.demoOptions
+      }
+    }
+
+    return {}
+  }
+
+  /**
+   * Returns the demo value.
+   *
+   * Возвращает демонстрационное значение.
+   */
+  private getDemoValue(): any {
+    if (this.item.demo) {
+      return this.item.demo
+    }
+
+    if (this.item.type === StorybookControl.boolean) {
+      return true
+    }
+
+    return undefined
+  }
+
   /**
    * Returns the category type of a property
    *
@@ -247,7 +292,8 @@ export class WikiStorybookItem {
         ...this.getDefaultValue(),
         ...this.getType()
       },
-      ...this.getDescription()
+      ...this.getDescription(),
+      ...this.getDemo()
     }
   }
 
@@ -276,7 +322,8 @@ export class WikiStorybookItem {
     return {
       control,
       table,
-      ...this.getDescription()
+      ...this.getDescription(),
+      ...this.getDemo()
     }
   }
 
@@ -292,7 +339,8 @@ export class WikiStorybookItem {
         ...this.getCategory(),
         ...this.getType()
       },
-      ...this.getDescription()
+      ...this.getDescription(),
+      ...this.getDemo()
     }
   }
 
@@ -310,7 +358,8 @@ export class WikiStorybookItem {
         ...this.getDefaultValue(),
         ...this.getType()
       },
-      ...this.getDescription()
+      ...this.getDescription(),
+      ...this.getDemo()
     }
   }
 
@@ -327,7 +376,8 @@ export class WikiStorybookItem {
         ...this.getDefaultValue(),
         ...this.getType()
       },
-      ...this.getDescription()
+      ...this.getDescription(),
+      ...this.getDemo()
     }
   }
 }

package/src/classes/WikiStorybookProp.ts

@@ -0,0 +1,109 @@
+import { isString, toKebabCase } from '@dxtmisha/functional-basic'
+import { type StorybookArgsItem, StorybookControl } from '../types/storybookTypes'
+
+/**
+ * Class for working with a single Storybook property.
+ *
+ * Класс для работы с одним свойством Storybook.
+ */
+export class WikiStorybookProp {
+  /**
+   * Constructor
+   * @param name property name / имя свойства
+   * @param item property configuration / конфигурация свойства
+   */
+  constructor(
+    public readonly name: string,
+    protected readonly item: StorybookArgsItem
+  ) {
+  }
+
+  /**
+   * Checks if the item is a demo item.
+   *
+   * Проверяет, является ли элемент демонстрационным.
+   */
+  isDemo(): boolean {
+    return this.item.isDemo === true
+  }
+
+  /**
+   * Returns the property configuration.
+   *
+   * Возвращает конфигурацию свойства.
+   */
+  get(): StorybookArgsItem {
+    return this.item
+  }
+
+  /**
+   * Returns the property name.
+   *
+   * Возвращает имя свойства.
+   */
+  getName(): string {
+    return toKebabCase(this.name)
+  }
+
+  /**
+   * Returns the default value of the property.
+   *
+   * Возвращает значение по умолчанию для свойства.
+   */
+  getDefaultValue(): any {
+    return this.item?.table?.defaultValue?.summary
+  }
+
+  /**
+   * Returns the property type.
+   *
+   * Возвращает тип свойства.
+   */
+  getType(): string {
+    if (this.item?.table?.type?.summary) {
+      return this.item.table.type.summary
+    }
+
+    if (isString(this.item.control)) {
+      return this.item.control
+    }
+
+    return this.item.control?.type ?? StorybookControl.string
+  }
+
+  /**
+   * Returns the property description.
+   *
+   * Возвращает описание свойства.
+   */
+  getDescription(): string {
+    return this.item.description ?? ''
+  }
+
+  /**
+   * Returns the property options.
+   *
+   * Возвращает опции свойства.
+   */
+  getOptions(): StorybookArgsItem['options'] {
+    return this.item.options
+  }
+
+  /**
+   * Returns the demo data.
+   *
+   * Возвращает демонстрационные данные.
+   */
+  getDemo(): any {
+    return this.item.demo
+  }
+
+  /**
+   * Returns the additional demo data.
+   *
+   * Возвращает дополнительные демонстрационные данные.
+   */
+  getDemoOptions(): Record<string, any> {
+    return this.item.demoOptions ?? {}
+  }
+}

package/src/library.ts

@@ -2,6 +2,7 @@
 export * from './classes/WikiStorybook'
 export * from './classes/WikiStorybookDescriptions'
 export * from './classes/WikiStorybookItem'
+export * from './classes/WikiStorybookProp'
 
 // Types
 export * from './types/storybookTypes'

package/src/media/descriptions/wikiDescriptions.ts

@@ -28,9 +28,11 @@ import { wikiDescriptionsMask } from './wikiDescriptionsMask'
 import { wikiDescriptionsMenu } from './wikiDescriptionsMenu'
 import { wikiDescriptionsModal } from './wikiDescriptionsModal'
 import { wikiDescriptionsMotionTransform } from './wikiDescriptionsMotionTransform'
+import { wikiDescriptionsPage } from './wikiDescriptionsPage'
 import { wikiDescriptionsProgress } from './wikiDescriptionsProgress'
 import { wikiDescriptionsRipple } from './wikiDescriptionsRipple'
 import { wikiDescriptionsScrollbar } from './wikiDescriptionsScrollbar'
+import { wikiDescriptionsSection } from './wikiDescriptionsSection'
 import { wikiDescriptionsSelect } from './wikiDescriptionsSelect'
 import { wikiDescriptionsSelectValue } from './wikiDescriptionsSelectValue'
 import { wikiDescriptionsSkeleton } from './wikiDescriptionsSkeleton'
@@ -67,9 +69,11 @@ export const wikiDescriptions: StorybookComponentsDescription = [
   wikiDescriptionsMenu,
   wikiDescriptionsModal,
   wikiDescriptionsMotionTransform,
+  wikiDescriptionsPage,
   wikiDescriptionsProgress,
   wikiDescriptionsRipple,
   wikiDescriptionsScrollbar,
+  wikiDescriptionsSection,
   wikiDescriptionsSelect,
   wikiDescriptionsSelectValue,
   wikiDescriptionsSkeleton,

package/src/media/descriptions/wikiDescriptionsAccordion.ts

@@ -154,5 +154,51 @@ export const wikiDescriptionsAccordion: StorybookComponentsDescriptionItem = {
 <StorybookDescriptions componentName={'Slot'} type={'description'}/>
 <StorybookDescriptions componentName={'Cell'} type={'slots'}/>
     `
+  },
+  ai: {
+    render: `
+<div :class="classDemo.item">
+  <Accordion :open="true" :auto-close="false" v-bind="args">
+    <div class="wiki-storybook-item--padding">
+      Hidden content
+    </div>
+  </Accordion>
+</div>
+    `,
+    description: `
+Accordion is a vertically stacking interactive component that allows users to reveal or hide content sections.
+It consists of a header (trigger) and a body (content) that expands/collapses with a smooth animation.
+
+**Key Features:**
+1. **Header (Trigger):**
+   - Uses the \`Cell\` component structure.
+   - Supports \`label\` (title), \`description\` (subtitle), and \`icon\` (leading icon).
+   - Includes a rotating arrow indicator (\`iconArrowDown\`) to show state.
+
+2. **Animation:**
+   - Uses \`MotionTransform\` for smooth height transitions.
+   - Content is unmounted or hidden when collapsed (depending on configuration).
+
+3. **Interaction:**
+   - Toggles on click or keyboard interaction (Enter/Space).
+   - Controlled via \`v-model:open\`.
+
+**Usage Examples:**
+
+- **Basic:**
+  \`<Accordion label="Settings">
+     <p>Settings content...</p>
+   </Accordion>\`
+
+- **With Description and Icon:**
+  \`<Accordion label="Profile" description="Manage your account" icon="person">
+     <ProfileForm />
+   </Accordion>\`
+
+- **Controlled:**
+  \`<Accordion v-model:open="isOpen" label="Controlled">
+     Content
+   </Accordion>\`
+    `
   }
 }

package/src/media/descriptions/wikiDescriptionsActionSheet.ts

@@ -207,5 +207,58 @@ export const wikiDescriptionsActionSheet: StorybookComponentsDescriptionItem = {
 <Canvas of={Component.ActionSheetAllSlots}/>
 <StorybookDescriptions componentName={'Window'} type={'slots'}/>
     `
+  },
+  ai: {
+    render: `
+<div :class="classDemo.item" style="min-width: 800px;">
+  <ActionSheet embedded open v-bind="args">
+    <template #control="{ binds }">
+      <button v-bind="binds">Open Menu</button>
+    </template>
+    <template #default>Content goes here...</template>
+  </ActionSheet>
+</div>
+    `,
+    description: `
+ActionSheet is a mobile-optimized modal component that slides up from the bottom of the screen (Bottom Sheet).
+It is designed to present a set of actions, choices, or secondary content, following standard mobile interface patterns (iOS/Material).
+
+**Note:** The \`embedded\` prop is used only for documentation examples to render the component inline. Do not use it in production code.
+
+**Key Features:**
+1. **Positioning & Animation:**
+   - Anchored to the bottom of the viewport.
+   - Slides up with an animation when opened.
+   - Renders a backdrop (overlay) to block background interactions.
+
+2. **Mobile Interactions:**
+   - **Touch Close:** Supports swiping down on the header to close the sheet (controlled by the \`touchClose\` prop).
+   - **Backdrop:** Clicking the overlay closes the sheet.
+   - **Scroll:** Automatically handles internal scrolling if content exceeds height.
+
+3. **Slots Structure:**
+   - \`#control\` - The trigger element (e.g., a button). Receives \`binds\` to toggle visibility.
+   - \`#title\` - The header area. Often contains the title and the drag handle (indicator).
+   - \`#default\` - The main content area.
+   - \`#footer\` - The bottom area, typically used for a "Cancel" button or primary actions.
+
+**Usage Examples:**
+
+- **With Trigger:**
+  \`<ActionSheet>
+     <template #control="{ binds }">
+       <button v-bind="binds">Open Menu</button>
+     </template>
+     <template #title>Select Option</template>
+     <template #default>
+       <p>List of options...</p>
+     </template>
+   </ActionSheet>\`
+
+- **Programmatic Control:**
+  \`<ActionSheet v-model:open="isOpen" touch-close>
+     <template #default>Content</template>
+   </ActionSheet>\`
+    `
   }
 }

package/src/media/descriptions/wikiDescriptionsActions.ts

@@ -157,5 +157,33 @@ export const wikiDescriptionsActions: StorybookComponentsDescriptionItem = {
 <StorybookDescriptions componentName={'Slot'} type={'default'}/>
 <StorybookDescriptions componentName={'Slot'} type={'secondary'}/>
     `
+  },
+  ai: {
+    description: `
+Actions is a layout component for organizing groups of buttons, typically used in dialog footers, card actions, or form controls.
+It manages spacing, alignment, and the separation between primary and secondary action groups.
+
+**Key Features:**
+1. **Groups:**
+   - \`list\`: Array of props for the main group of buttons (usually right-aligned or primary).
+   - \`listSecondary\`: Array of props for the secondary group (usually left-aligned).
+
+2. **Alignment (\`align\`):**
+   - \`left\`: Aligns all buttons to the left.
+   - \`center\`: Centers the buttons.
+   - \`right\`: Aligns all buttons to the right (default for dialogs).
+   - \`block\`: Stretches buttons to fill the width.
+
+3. **Button Configuration:**
+   - Items in \`list\` and \`listSecondary\` are passed directly to the \`Button\` component.
+   - \`buttonAttrs\`: Common props applied to all buttons in the main list.
+   - \`buttonSecondaryAttrs\`: Common props applied to all buttons in the secondary list.
+
+**Usage Examples:**
+
+- **Dialog Footer:** \`<Actions align="right" :list="[{ label: 'Cancel' }, { label: 'Ok', primary: true }]" />\`
+- **Split Actions:** \`<Actions :list="[{ label: 'Save' }]" :listSecondary="[{ label: 'Delete', text: true }]" />\` (Save on right, Delete on left)
+- **Full Width:** \`<Actions align="block" :list="[{ label: 'Login', primary: true }]" />\`
+      `
   }
 }

package/src/media/descriptions/wikiDescriptionsAnchor.ts

@@ -38,5 +38,41 @@ export const wikiDescriptionsAnchor: StorybookComponentsDescriptionItem = {
     slots: `
 <StorybookDescriptions componentName={'Slot'} type={'default'}/>
 `
+  },
+  ai: {
+    render: `
+<div :class="classDemo.item">
+  <Anchor href="#" v-bind="args"/>
+</div>
+    `,
+    description: `
+Anchor is a fundamental navigation component used to create hyperlinks and anchor points.
+It wraps the standard HTML \`<a>\` tag functionality with additional utilities for smooth scrolling and clipboard interactions.
+
+**Key Features:**
+1. **Navigation:**
+   - Handles standard navigation via \`href\`.
+   - Can be used for both internal (router) and external links.
+
+2. **Smooth Scrolling:**
+   - The \`scroll\` prop enables smooth scrolling animation when navigating to an element ID (e.g., \`href="#section"\`).
+
+3. **Clipboard Interaction:**
+   - The \`isCopy\` prop turns the component into a trigger that copies the link or value to the clipboard.
+
+4. **Slots:**
+   - \`#default\`: The content of the link (text, icons, or other elements).
+
+**Usage Examples:**
+
+- **Basic Link:**
+  \`<Anchor href="/about">About Us</Anchor>\`
+
+- **Scroll to Anchor:**
+  \`<Anchor href="#contact" scroll>Contact</Anchor>\`
+
+- **Copy Link:**
+  \`<Anchor href="https://example.com" is-copy>Copy URL</Anchor>\`
+    `
   }
 }

package/src/media/descriptions/wikiDescriptionsArrow.ts

@@ -177,5 +177,38 @@ export const wikiDescriptionsArrow: StorybookComponentsDescriptionItem = {
 <StorybookDescriptions componentName={'Arrow'} type={'arrow'}/>
 <Canvas of={Component.ArrowBasic}/>
 `
+  },
+  ai: {
+    render: `
+<div :class="classDemo.item" style="position: relative; width: 48px; height: 48px; background-color: oklch(93.2% 0.032 255.585);">
+    <Arrow position="top" v-bind="args"/>
+</div>
+    `,
+    description: `
+Arrow is a functional component that renders a triangular pointer connecting a container (like a tooltip, popover, or dropdown) to a target element.
+It is designed to automatically blend with the parent container's styles (background, border) to create a seamless speech-bubble effect.
+
+**Key Features:**
+1. **Target Linking:** Points to a specific DOM element defined by \`elementTarget\` (selector or HTMLElement).
+2. **Auto-Positioning:** Automatically calculates the correct placement (top, bottom, left, right) relative to the container and the target.
+3. **Style Inheritance:** Inherits \`background-color\`, \`border-color\`, and \`border-width\` from the parent element to match the container's visual style perfectly.
+4. **Reactive Updates:** Updates its position when the target or container moves (often used within \`Window\` or floating UI components).
+
+**When to use:**
+- Inside **Tooltips** to point to the hovered element.
+- Inside **Popovers** or **Dropdowns** to indicate the trigger source.
+- For any floating UI that needs a directional indicator.
+
+**Usage Examples:**
+
+- **Basic Tooltip Arrow:**
+  \`<div class="tooltip">
+     Message
+     <Arrow element-target="#button-id" />
+   </div>\`
+
+- **With Auto Positioning:**
+  \`<Arrow position="auto" element-target=".target-element" />\`
+    `
   }
 }

package/src/media/descriptions/wikiDescriptionsBadge.ts

@@ -134,5 +134,48 @@ export const wikiDescriptionsBadge: StorybookComponentsDescriptionItem = {
     slots: `
 <StorybookDescriptions componentName={'Slot'} type={'default'}/>
     `
+  },
+  ai: {
+    render: `
+<div :class="classDemo.item" style="min-width: 48px; min-height: 48px;">
+  <Badge overlap="static" v-bind="args"/>
+</div>
+    `,
+    description: `
+Badge is a small visual indicator used to display status, counts, or short labels (tags).
+It is typically positioned over the corner of another element (like an icon or avatar) or used inline.
+
+**Key Features:**
+1. **Content Handling:**
+   - **Numeric:** Displays numbers via \`label\`. Use \`labelMax\` to cap the value (e.g., "99+").
+   - **Text:** Displays short text strings.
+   - **Icon:** Can display an icon via the \`icon\` prop.
+   - **Dot:** If \`dot\` is true, renders as a small circle without text (status indicator).
+
+2. **Positioning (\`overlap\`):**
+   - \`static\`: Renders inline (default flow).
+   - \`rectangular\`: Positioned absolutely over a rectangular parent.
+   - \`circular\`: Positioned absolutely over a circular parent (adjusts coordinates).
+   - **Alignment:** Controlled by \`vertical\` (top/bottom) and \`horizontal\` (right/left).
+
+3. **Styling:**
+   - Supports variants: \`primary\`, \`secondary\`, \`outline\`.
+   - \`hide\`: Toggles visibility.
+   - \`dot\`: Switches to dot mode.
+
+**Usage Examples:**
+
+- **Notification Count:**
+  \`<div class="relative-container">
+     <Icon name="notifications" />
+     <Badge label="5" overlap="circular" vertical="top" horizontal="right" />
+   </div>\`
+
+- **Status Dot:**
+  \`<Badge dot primary />\`
+
+- **Inline Tag:**
+  \`<Badge label="New" overlap="static" />\`
+    `
   }
 }