@uibit/carousel 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,17 @@
 # Carousel
 
+[![NPM Version](https://img.shields.io/npm/v/@uibit/carousel.svg?style=flat-square&color=black)](https://www.npmjs.com/package/@uibit/carousel)
+
+
 [Interactive Demonstration](https://rawlings.github.io/uibit/components/carousel)
 
+## Installation
+
+```bash
+npm install @uibit/carousel
+```
+
+
 Carousel provides a fluid and responsive content presentation display that invites exploration. With smooth transitions, touch responsiveness, and elegant pagination control, it showcases visual content without cluttering the interface structure.
 
 ## Value Delivery

package/custom-elements.json

@@ -8,7 +8,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Accessible, scroll-driven carousel with keyboard navigation, auto-play,\nand configurable items-per-view via CSS custom properties.",
+          "description": "Accessible, scroll-driven carousel with keyboard navigation, auto-play,",
           "name": "UIBitCarousel",
           "cssProperties": [
             {
@@ -350,11 +350,13 @@
             },
             {
               "kind": "method",
-              "name": "prev"
+              "name": "prev",
+              "description": "\n\nReturns the carousel to the previous slide."
             },
             {
               "kind": "method",
-              "name": "next"
+              "name": "next",
+              "description": "\n\nAdvances the carousel to the next slide."
             },
             {
               "kind": "method",
@@ -366,7 +368,8 @@
                     "text": "number"
                   }
                 }
-              ]
+              ],
+              "description": "\n\nNavigates the carousel to a specific slide index."
             },
             {
               "kind": "method",
@@ -390,6 +393,211 @@
               "kind": "method",
               "name": "handleSlotChange",
               "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "locale",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "BCP 47 locale string for formatting and localization. Defaults to inherited document language.",
+              "attribute": "locale",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "resolvedLocale",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Resolves the active locale for formatting and localization.\nChecks the `locale` property first, then traverses up the DOM to find\nthe nearest ancestor with a `lang` attribute, and finally falls back\nto undefined (which defaults to browser locale).",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "_disposables",
+              "type": {
+                "text": "Set<() => void>"
+              },
+              "privacy": "private",
+              "default": "new Set()",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "createProperty",
+              "static": true,
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "PropertyKey"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "PropertyDeclaration"
+                  }
+                }
+              ],
+              "description": "Overrides createProperty to automatically map camelCase property names\nto kebab-case attribute names by default.",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "finalizeStyles",
+              "static": true,
+              "return": {
+                "type": {
+                  "text": "Array<any>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "styles",
+                  "optional": true,
+                  "type": {
+                    "text": "CSSResultGroup"
+                  }
+                }
+              ],
+              "description": "Automatically prepends basic layout resets (border-box) to the\ncomponent's final styles.",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "dispatchCustomEvent",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "detail",
+                  "optional": true,
+                  "type": {
+                    "text": "T"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "Omit<CustomEventInit<T>, 'detail'>"
+                  }
+                }
+              ],
+              "description": "Helper to dispatch a custom event with standard bubbles and composed options.",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "getCssPropertyValue",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "propertyName",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Helper to retrieve a computed CSS custom property value from the element.",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "registerDisposable",
+              "parameters": [
+                {
+                  "name": "cleanup",
+                  "type": {
+                    "text": "() => void"
+                  }
+                }
+              ],
+              "description": "Register a cleanup function to be executed when the element is disconnected from the DOM.",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "listen",
+              "return": {
+                "type": {
+                  "text": "() => void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "target",
+                  "type": {
+                    "text": "EventTarget"
+                  }
+                },
+                {
+                  "name": "type",
+                  "type": {
+                    "text": "K"
+                  }
+                },
+                {
+                  "name": "listener",
+                  "type": {
+                    "text": "(this: EventTarget, ev: HTMLElementEventMap[K]) => any"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "boolean | AddEventListenerOptions"
+                  }
+                }
+              ],
+              "description": "Utility to add an event listener that is automatically cleaned up when the element is disconnected.",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
             }
           ],
           "events": [
@@ -428,12 +636,36 @@
               "default": "true",
               "description": "When `true`, the carousel wraps from the last slide back to the first.",
               "fieldName": "loop"
+            },
+            {
+              "name": "locale",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "BCP 47 locale string for formatting and localization. Defaults to inherited document language.",
+              "fieldName": "locale",
+              "inheritedFrom": {
+                "name": "UIBitElement",
+                "module": "../../platform/core/src/element.ts"
+              }
+            }
+          ],
+          "cssStates": [
+            {
+              "name": "playing",
+              "description": "Active when auto-play is running."
+            },
+            {
+              "name": "dragging",
+              "description": "Active when dragging viewport."
             }
           ],
           "superclass": {
             "name": "UIBitElement",
             "package": "@uibit/core"
           },
+          "summary": "A premium, scroll-driven carousel component with full accessibility controls.\nand configurable items-per-view via CSS custom properties.",
           "tagName": "uibit-carousel",
           "customElement": true
         }
@@ -478,6 +710,14 @@
             "module": "./carousel"
           }
         },
+        {
+          "kind": "js",
+          "name": "UIBitCarousel",
+          "declaration": {
+            "name": "UIBitCarousel",
+            "module": "./carousel"
+          }
+        },
         {
           "kind": "js",
           "name": "CarouselConfig",
@@ -522,6 +762,250 @@
       "path": "src/types.ts",
       "declarations": [],
       "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "../../platform/core/src/element.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "A foundational base class for all UIBit web components.\nProvides custom event helpers, default kebab-case attribute mapping,\nautomatic cleanup/disposable tracking, and auto-injected reset styles.",
+          "name": "UIBitElement",
+          "members": [
+            {
+              "kind": "field",
+              "name": "locale",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "BCP 47 locale string for formatting and localization. Defaults to inherited document language.",
+              "attribute": "locale"
+            },
+            {
+              "kind": "field",
+              "name": "resolvedLocale",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Resolves the active locale for formatting and localization.\nChecks the `locale` property first, then traverses up the DOM to find\nthe nearest ancestor with a `lang` attribute, and finally falls back\nto undefined (which defaults to browser locale).",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "_disposables",
+              "type": {
+                "text": "Set<() => void>"
+              },
+              "privacy": "private",
+              "default": "new Set()"
+            },
+            {
+              "kind": "method",
+              "name": "createProperty",
+              "static": true,
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "PropertyKey"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "PropertyDeclaration"
+                  }
+                }
+              ],
+              "description": "Overrides createProperty to automatically map camelCase property names\nto kebab-case attribute names by default."
+            },
+            {
+              "kind": "method",
+              "name": "finalizeStyles",
+              "static": true,
+              "return": {
+                "type": {
+                  "text": "Array<any>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "styles",
+                  "optional": true,
+                  "type": {
+                    "text": "CSSResultGroup"
+                  }
+                }
+              ],
+              "description": "Automatically prepends basic layout resets (border-box) to the\ncomponent's final styles."
+            },
+            {
+              "kind": "method",
+              "name": "dispatchCustomEvent",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "detail",
+                  "optional": true,
+                  "type": {
+                    "text": "T"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "Omit<CustomEventInit<T>, 'detail'>"
+                  }
+                }
+              ],
+              "description": "Helper to dispatch a custom event with standard bubbles and composed options."
+            },
+            {
+              "kind": "method",
+              "name": "getCssPropertyValue",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "propertyName",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Helper to retrieve a computed CSS custom property value from the element."
+            },
+            {
+              "kind": "method",
+              "name": "registerDisposable",
+              "parameters": [
+                {
+                  "name": "cleanup",
+                  "type": {
+                    "text": "() => void"
+                  }
+                }
+              ],
+              "description": "Register a cleanup function to be executed when the element is disconnected from the DOM."
+            },
+            {
+              "kind": "method",
+              "name": "listen",
+              "return": {
+                "type": {
+                  "text": "() => void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "target",
+                  "type": {
+                    "text": "EventTarget"
+                  }
+                },
+                {
+                  "name": "type",
+                  "type": {
+                    "text": "K"
+                  }
+                },
+                {
+                  "name": "listener",
+                  "type": {
+                    "text": "(this: EventTarget, ev: HTMLElementEventMap[K]) => any"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "boolean | AddEventListenerOptions"
+                  }
+                }
+              ],
+              "description": "Utility to add an event listener that is automatically cleaned up when the element is disconnected."
+            },
+            {
+              "kind": "method",
+              "name": "listen",
+              "return": {
+                "type": {
+                  "text": "() => void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "target",
+                  "type": {
+                    "text": "EventTarget"
+                  }
+                },
+                {
+                  "name": "type",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "listener",
+                  "type": {
+                    "text": "EventListenerOrEventListenerObject"
+                  }
+                },
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "boolean | AddEventListenerOptions"
+                  }
+                }
+              ]
+            }
+          ],
+          "attributes": [
+            {
+              "name": "locale",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "BCP 47 locale string for formatting and localization. Defaults to inherited document language.",
+              "fieldName": "locale"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UIBitElement",
+          "declaration": {
+            "name": "UIBitElement",
+            "module": "../../platform/core/src/element.ts"
+          }
+        }
+      ]
     }
   ]
 }

package/dist/carousel.d.ts

@@ -2,6 +2,8 @@ import { UIBitElement } from '@uibit/core';
 import type { CarouselConfig } from './types';
 /**
  * Accessible, scroll-driven carousel with keyboard navigation, auto-play,
+
+ * @summary A premium, scroll-driven carousel component with full accessibility controls.
  * and configurable items-per-view via CSS custom properties.
  *
  * @fires {{ index: number, totalSlides: number }} slide-change - Fired when the active slide changes
@@ -31,7 +33,9 @@ import type { CarouselConfig } from './types';
  * @csspart indicators - The indicator dot group
  * @csspart indicator - Each indicator dot
  * @csspart indicator-active - Added to the active indicator dot
- */
+ 
+ * @cssstate playing - Active when auto-play is running.
+ * @cssstate dragging - Active when dragging viewport.*/
 export declare class UIBitCarousel extends UIBitElement {
     static styles: import("lit").CSSResult;
     /** Automatically advance slides on a timer. */
@@ -73,8 +77,29 @@ export declare class UIBitCarousel extends UIBitElement {
     private stopAutoPlay;
     private getSlides;
     private updateNavigationState;
+    /**
+  
+  
+     * Returns the carousel to the previous slide.
+  
+  
+     */
     prev(): void;
+    /**
+  
+  
+     * Advances the carousel to the next slide.
+  
+  
+     */
     next(): void;
+    /**
+  
+  
+     * Navigates the carousel to a specific slide index.
+  
+  
+     */
     goToSlide(index: number): void;
     private scrollToSlide;
     private emitSlideChange;

package/dist/carousel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["../src/carousel.ts"],"names":[],"mappings":"AACA,OAAO,EAAgD,YAAY,EAAE,MAAM,aAAa,CAAC;AAGzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBACa,aAAc,SAAQ,YAAY;IAC7C,MAAM,CAAC,MAAM,0BAAU;IAEvB,+CAA+C;IACM,QAAQ,UAAS;IACtE,+CAA+C;IACc,gBAAgB,SAAQ;IACrF,6EAA6E;IAChD,IAAI,UAAQ;IAEzC,IAAI,YAAY,IAAI,MAAM,CAIzB;IAED,IAAI,GAAG,IAAI,MAAM,CAIhB;IAED,IAAI,QAAQ,IAAI,MAAM,CAOrB;IAE2B,OAAO,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACxB,WAAW,CAAC,EAAE,eAAe,CAAC;IAEjD,YAAY,SAAK;IACjB,WAAW,SAAK;IAChB,OAAO,UAAS;IAChB,OAAO,UAAQ;IAExB,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,cAAc,CAAC,CAAiB;IACxC,OAAO,CAAC,aAAa,CAAC,CAAuB;IAC7C,OAAO,CAAC,uBAAuB,CAA8B;IAC7D,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,yBAAyB,CAAC,CAAS;IAC3C,OAAO,CAAC,qBAAqB,CAAS;IAEtC,OAAO,CAAC,kBAAkB,CAGxB;IAEF,OAAO,CAAC,kBAAkB,CAKxB;IAEF,OAAO,CAAC,aAAa,CAGnB;IAEF,OAAO,CAAC,cAAc,CAKpB;IAEF,YAAY,MAAM,CAAC,EAAE,cAAc,EAgBlC;IAED,SAAS,CAAC,YAAY,SASrB;IAED,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,QAW9C;IAED,oBAAoB,SAMnB;IAED,OAAO,CAAC,aAAa;IAqBrB,OAAO,CAAC,kBAAkB;IAuC1B,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,SAAS;IAgBjB,OAAO,CAAC,qBAAqB;IAK7B,IAAI,SAMH;IAED,IAAI,SAMH;IAED,SAAS,CAAC,KAAK,EAAE,MAAM,QAItB;IAED,OAAO,CAAC,aAAa;IA6CrB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,gBAAgB;IAIxB,MAAM,oCAoEL;CACF;eAEc,aAAa"}
+{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["../src/carousel.ts"],"names":[],"mappings":"AACA,OAAO,EAAgD,YAAY,EAAE,MAAM,aAAa,CAAC;AAGzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wDAmCwD;AACxD,qBACa,aAAc,SAAQ,YAAY;IAC7C,MAAM,CAAC,MAAM,0BAAU;IAEvB,+CAA+C;IACM,QAAQ,UAAS;IACtE,+CAA+C;IACc,gBAAgB,SAAQ;IACrF,6EAA6E;IAChD,IAAI,UAAQ;IAEzC,IAAI,YAAY,IAAI,MAAM,CAIzB;IAED,IAAI,GAAG,IAAI,MAAM,CAIhB;IAED,IAAI,QAAQ,IAAI,MAAM,CAOrB;IAE2B,OAAO,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACxB,WAAW,CAAC,EAAE,eAAe,CAAC;IAEjD,YAAY,SAAK;IACjB,WAAW,SAAK;IAChB,OAAO,UAAS;IAChB,OAAO,UAAQ;IAExB,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,cAAc,CAAC,CAAiB;IACxC,OAAO,CAAC,aAAa,CAAC,CAAuB;IAC7C,OAAO,CAAC,uBAAuB,CAA8B;IAC7D,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,yBAAyB,CAAC,CAAS;IAC3C,OAAO,CAAC,qBAAqB,CAAS;IAEtC,OAAO,CAAC,kBAAkB,CAGxB;IAEF,OAAO,CAAC,kBAAkB,CAKxB;IAEF,OAAO,CAAC,aAAa,CAGnB;IAEF,OAAO,CAAC,cAAc,CAKpB;IAEF,YAAY,MAAM,CAAC,EAAE,cAAc,EAgBlC;IAED,SAAS,CAAC,YAAY,SASrB;IAED,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,QAW9C;IAED,oBAAoB,SAMnB;IAED,OAAO,CAAC,aAAa;IAqBrB,OAAO,CAAC,kBAAkB;IAuC1B,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,SAAS;IAgBjB,OAAO,CAAC,qBAAqB;IAK7B;;;;;;OAMG;IAGH,IAAI,SAMH;IAED;;;;;;OAMG;IAGH,IAAI,SAMH;IAED;;;;;;OAMG;IAGH,SAAS,CAAC,KAAK,EAAE,MAAM,QAItB;IAED,OAAO,CAAC,aAAa;IA6CrB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,gBAAgB;IAIxB,MAAM,oCAoEL;CACF;eAEc,aAAa"}

package/dist/carousel.js

@@ -11,6 +11,8 @@ import { property, query, state } from 'lit/decorators.js';
 import { styles } from './styles';
 /**
  * Accessible, scroll-driven carousel with keyboard navigation, auto-play,
+
+ * @summary A premium, scroll-driven carousel component with full accessibility controls.
  * and configurable items-per-view via CSS custom properties.
  *
  * @fires {{ index: number, totalSlides: number }} slide-change - Fired when the active slide changes
@@ -40,7 +42,9 @@ import { styles } from './styles';
  * @csspart indicators - The indicator dot group
  * @csspart indicator - Each indicator dot
  * @csspart indicator-active - Added to the active indicator dot
- */
+ 
+ * @cssstate playing - Active when auto-play is running.
+ * @cssstate dragging - Active when dragging viewport.*/
 let UIBitCarousel = class UIBitCarousel extends UIBitElement {
     static { this.styles = styles; }
     get itemsPerView() {
@@ -257,6 +261,13 @@ let UIBitCarousel = class UIBitCarousel extends UIBitElement {
         this.canPrev = this.currentIndex > 0 || this.loop;
         this.canNext = this.currentIndex < this.totalSlides - 1 || this.loop;
     }
+    /**
+  
+  
+     * Returns the carousel to the previous slide.
+  
+  
+     */
     prev() {
         if (this.currentIndex > 0) {
             this.scrollToSlide(this.currentIndex - 1);
@@ -265,6 +276,13 @@ let UIBitCarousel = class UIBitCarousel extends UIBitElement {
             this.scrollToSlide(this.totalSlides - 1);
         }
     }
+    /**
+  
+  
+     * Advances the carousel to the next slide.
+  
+  
+     */
     next() {
         if (this.currentIndex < this.totalSlides - 1) {
             this.scrollToSlide(this.currentIndex + 1);
@@ -273,6 +291,13 @@ let UIBitCarousel = class UIBitCarousel extends UIBitElement {
             this.scrollToSlide(0);
         }
     }
+    /**
+  
+  
+     * Navigates the carousel to a specific slide index.
+  
+  
+     */
     goToSlide(index) {
         if (index >= 0 && index < this.totalSlides) {
             this.scrollToSlide(index);