panelset 1.0.7 → 1.2.0

package/dist/types/index.d.ts

@@ -0,0 +1,12 @@
+import { PanelElement } from './panel.element.js';
+import { PanelSetElement } from './panelset.element.js';
+import { PanelControlElement, registerPanelControl } from './panelcontrol.element.js';
+export { PanelSet } from './panelset.js';
+export type { PanelSetConfig, ReadyEventDetail, BeforeActivateEventDetail, BeforeOpenEventDetail, ActivationEventDetail, ActivationAbortedEventDetail, HandlerOptions, ShowOptions, AsyncContentHandler, } from './panelset.types.js';
+export { Panel } from './panel.js';
+export type { PanelConfig, BeforeOpenEventDetail as PanelBeforeOpenEventDetail, PanelEventDetail, AsyncOpenHandler, } from './panel.types.js';
+export { PanelControl } from './panelcontrol.js';
+export type { PanelControlConfig } from './panelcontrol.types.js';
+export { PanelElement, PanelSetElement, PanelControlElement, registerPanelControl };
+export declare function register(prefix?: string): void;
+export { PanelSet as default } from './panelset.js';

package/dist/types/index.iife.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/panel.d.ts

@@ -0,0 +1,56 @@
+import { PanelConfig, AsyncOpenHandler } from './panel.types.js';
+import { AttrMap } from './functions/config.js';
+declare global {
+    interface HTMLElement {
+        panel?: Panel;
+    }
+}
+export declare class Panel {
+    element: HTMLElement;
+    config: Required<PanelConfig>;
+    private _returnFocusTarget;
+    private _tempCloseGroup;
+    private _anim;
+    private _listenerController;
+    private _activating;
+    static defaults: Required<PanelConfig>;
+    static readonly attrs: AttrMap<PanelConfig>;
+    private static readonly _nativeInterpolateSize;
+    private static _autoIdCounter;
+    static init(selectorOrOptions?: string | PanelConfig, options?: PanelConfig): Panel[];
+    constructor(elementOrSelector: HTMLElement | string, options?: PanelConfig);
+    private _log;
+    private _parsePanelParam;
+    private _updatePanelParam;
+    private _resolveStateConfig;
+    private _persistState;
+    private _resolveInitialState;
+    private _cssProp;
+    private _wireImplicitTriggers;
+    private _bindTriggers;
+    private _setTriggerState;
+    private _cleanupTempClose;
+    private _closeGroupSiblings;
+    private _handleAutoFocus;
+    private _dispatch;
+    get isOpen(): boolean;
+    open(event?: Event): Promise<void>;
+    private _openAsync;
+    private _openSync;
+    /**
+     * Register a handler for async content loading before the panel opens.
+     * The handler receives the panel element and an AbortSignal.
+     * If it returns a Promise, the panel waits for it before animating open.
+     */
+    onBeforeOpen(handler: AsyncOpenHandler, options?: {
+        once?: boolean;
+    }): void;
+    close(event?: Event): void;
+    toggle(event?: Event): void;
+    /**
+     * Tear down this instance. Removes listeners, resets element state, and
+     * clears element.panel so Panel.init() can re-bind it.
+     */
+    destroy(): void;
+}
+export default Panel;

package/dist/types/panel.element.d.ts

@@ -0,0 +1,4 @@
+export declare class PanelElement extends HTMLElement {
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}

package/dist/types/panel.types.d.ts

@@ -0,0 +1,28 @@
+import { AutoFocusMode } from './functions/focus.js';
+export interface PanelConfig {
+    axis?: 'vertical' | 'horizontal';
+    align?: 'start' | 'end' | 'center';
+    closeOnResize?: boolean;
+    transitions?: boolean;
+    autoFocus?: AutoFocusMode;
+    returnFocus?: boolean;
+    closeSiblings?: boolean;
+    loadingDelay?: number;
+    loadingHeight?: number;
+    interruptible?: boolean;
+    persist?: boolean;
+    deepLink?: boolean;
+    debug?: boolean;
+}
+export interface BeforeOpenEventDetail {
+    signal: AbortSignal;
+    /** Underlying mechanism the open awaits; prefer waitUntil(). */
+    promise: Promise<unknown> | null;
+    /** Delay the open until p resolves. May be called more than once (awaits all). */
+    waitUntil(p: Promise<unknown>): void;
+    trigger: HTMLElement | null;
+}
+export interface PanelEventDetail {
+    trigger: HTMLElement | null;
+}
+export type AsyncOpenHandler = (element: HTMLElement, signal: AbortSignal) => Promise<void> | void;

package/dist/types/panelcontrol.d.ts

@@ -0,0 +1,64 @@
+import { PanelControlConfig } from './panelcontrol.types.js';
+import { ShowOptions } from './panelset.types.js';
+import { AttrMap } from './functions/config.js';
+declare global {
+    interface HTMLElement {
+        panelControl?: PanelControl;
+    }
+}
+export declare class PanelControl {
+    static defaults: Required<Omit<PanelControlConfig, 'selector'>>;
+    static readonly attrs: AttrMap<PanelControlConfig>;
+    element: HTMLElement;
+    config: Required<Omit<PanelControlConfig, 'selector'>>;
+    private _setEl;
+    private _controller;
+    private _isTablist;
+    private _activationWired;
+    /**
+     * Initialise all PanelControl containers matching the selector.
+     * @param selectorOrOptions - CSS selector string or config object.
+     * @param options - Config (used when the first argument is a selector).
+     */
+    static init(selectorOrOptions?: string | PanelControlConfig, options?: PanelControlConfig): PanelControl[];
+    constructor(elementOrSelector: HTMLElement | string, options?: PanelControlConfig);
+    /**
+     * The PanelSet container this control drives. Resolved lazily on first access
+     * and then cached — so a PanelSet added to the DOM after init is still found.
+     */
+    get panelSetElement(): HTMLElement | null;
+    /** The live PanelSet instance this control drives, if initialised. */
+    get panelSet(): import('./panelset.js').PanelSet | undefined;
+    /** Activate a tab's panel through the linked PanelSet. */
+    show(panelId: string, options?: ShowOptions): void;
+    /**
+     * Lock or unlock a tab. PanelControl only applies the state it is told to
+     * apply — it does not decide *when* a tab should be locked (that is the
+     * caller's concern, e.g. a flow controller). 'disabled' sets aria-disabled so
+     * keyboard nav skips the tab and clicks / Enter no longer activate it;
+     * 'enabled' clears it. A tab may carry data-pc-disabled-hint="hintId"; that
+     * hint is attached to aria-describedby only while the tab is disabled, so a
+     * focusable (aria-disabled) tab can explain why it is locked.
+     * @param panelId - aria-controls target id of the tab(s) to update.
+     * @param state - 'enabled' or 'disabled'.
+     */
+    setTabState(panelId: string, state: 'enabled' | 'disabled'): void;
+    private _log;
+    private _reflectCloseable;
+    private _resolvePanelSet;
+    private _onElementResolved;
+    private _bindTriggers;
+    private _activate;
+    private _tabs;
+    private _enabled;
+    private _setRoving;
+    private _ensureRovingStop;
+    private _setupKeyboard;
+    private _onActivation;
+    private _onKeydown;
+    private _autoActivate;
+    private _autoFocusInPlay;
+    /** Remove all listeners and drop the reference from the element. */
+    destroy(): void;
+}
+export default PanelControl;

package/dist/types/panelcontrol.element.d.ts

@@ -0,0 +1,9 @@
+export declare class PanelControlElement extends HTMLElement {
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}
+/**
+ * Register the <ps-panelcontrol> custom element.
+ * @param prefix - Element name prefix. Defaults to 'ps' → <ps-panelcontrol>.
+ */
+export declare function registerPanelControl(prefix?: string): void;

package/dist/types/panelcontrol.types.d.ts

@@ -0,0 +1,14 @@
+export interface PanelControlConfig {
+    /** CSS selector for init(). Defaults to '[data-panelcontrol]'. */
+    selector?: string;
+    /**
+     * Keyboard activation for tablist controls.
+     * - 'manual' (default): arrow keys move focus; Enter/Space (or click) activates.
+     * - 'auto': arrow keys move focus AND activate — but auto self-downgrades to
+     *   manual whenever the PanelSet uses autoFocus or async content, since
+     *   activating on every arrow would fight focus or fire loads.
+     */
+    activation?: 'manual' | 'auto';
+    /** Verbose console logging. */
+    debug?: boolean;
+}

package/dist/types/panelset.d.ts

@@ -0,0 +1,149 @@
+import { PanelSetConfig, HandlerOptions, ShowOptions, AsyncContentHandler } from './panelset.types.js';
+import { AttrMap } from './functions/config.js';
+declare global {
+    interface HTMLElement {
+        panelSet?: PanelSet;
+    }
+}
+export declare class PanelSet {
+    static defaults: Required<Omit<PanelSetConfig, 'selector'>>;
+    element: HTMLElement;
+    config: Required<Omit<PanelSetConfig, 'selector'>>;
+    panels: HTMLElement[];
+    activePanel: HTMLElement;
+    panelWrapper: HTMLElement;
+    pendingPanel: HTMLElement;
+    /** True once an async content handler has been registered via onBeforeOpen(). */
+    hasAsyncContent: boolean;
+    private _animShow;
+    private _animOpenClose;
+    private _isLoadingAsync;
+    private _activating;
+    private _switchDirection;
+    private _returnFocusTarget;
+    private _heightObserver;
+    private _verbController;
+    private static readonly _nativeInterpolateSize;
+    private static _verbDelegationInstalled;
+    static readonly attrs: AttrMap<PanelSetConfig>;
+    /**
+     * Initialize PanelSet instances
+     * @param selectorOrOptions - CSS selector string or config object
+     * @param options - Additional config options (when first param is selector)
+     * @returns Array of PanelSet instances
+     */
+    static init(selectorOrOptions?: string | PanelSetConfig, options?: PanelSetConfig): PanelSet[];
+    constructor(elementOrSelector: HTMLElement | string, options?: PanelSetConfig);
+    private _observeTrackHeight;
+    private _log;
+    private get _isClosed();
+    private _parsePanelParam;
+    private _persistState;
+    private _updatePanelParam;
+    private _resolveInitialPanel;
+    private static _validateElement;
+    private _autoWrapPanels;
+    private _collectPanels;
+    private _internalInit;
+    private _dispatch;
+    private _getVerticalMetrics;
+    private _measureHeight;
+    private _updateHighestPanel;
+    private _updateTabTriggers;
+    private _reflectLabels;
+    private _uniqueId;
+    private _setTriggersActivating;
+    private _cleanupPanels;
+    private _resolveAutoFocus;
+    private _handleAutoFocus;
+    private _animateOpenClose;
+    /**
+     * Get the ID of the currently active panel
+     * @returns Panel ID or null if no panel is active
+     */
+    getActive(): string | null;
+    /**
+     * Re-scan the DOM for this set's panels and reconcile internal state — the
+     * active panel, trigger state, and the Prev/Next end-of-range disabling. Call
+     * after adding, removing, or reordering [role="tabpanel"] elements at runtime
+     * (e.g. lazy or windowed wizards). The active panel is preserved when it is
+     * still present; otherwise it falls back to the marked .active panel, then the
+     * first panel. Newly added panels are initialised to the hidden state.
+     * Call when idle (not mid-transition).
+     */
+    refresh(): void;
+    /**
+     * Insert a panel at runtime and refresh. The node is appended to the wrapper
+     * unless a position is given. Ensures the element carries role="tabpanel".
+     * @param panel - The [role="tabpanel"] element to add.
+     * @param position - { before } / { after } an existing panel id, or { index }.
+     * @returns The inserted panel.
+     */
+    addPanel(panel: HTMLElement, position?: {
+        before?: string;
+        after?: string;
+        index?: number;
+    }): HTMLElement;
+    /**
+     * Remove a panel by id and refresh.
+     * @param panelId - ID of the panel to remove.
+     */
+    removePanel(panelId: string): void;
+    /**
+     * Destroy this instance
+     */
+    destroy(): void;
+    private _edgeInfo;
+    private static _installVerbDelegation;
+    private static _resolveVerbSet;
+    private static _onVerbClick;
+    private _initVerbButtons;
+    private _reflectEnds;
+    private _onActivationEdge;
+    private _reflectVerbEndState;
+    private _applyVerbDisabled;
+    private _disableVerbNative;
+    private _verbFocusFallback;
+    private _verbButtonsFor;
+    /**
+     * Activate the next panel in DOM order. Stops at the last panel unless the
+     * `loop` option is set, in which case it wraps to the first.
+     * @param options - Configuration options for the activation
+     */
+    next(options?: ShowOptions): void;
+    /**
+     * Activate the previous panel in DOM order. Stops at the first panel unless
+     * the `loop` option is set, in which case it wraps to the last.
+     * @param options - Configuration options for the activation
+     */
+    prev(options?: ShowOptions): void;
+    private _step;
+    /**
+     * Open a closable panelset
+     * @param options - Configuration options
+     */
+    open(options?: ShowOptions): void;
+    /**
+     * Close a closable panelset
+     * @param options - Configuration options
+     */
+    close(options?: ShowOptions): void;
+    /**
+     * Toggle a closable panelset between open and closed
+     * @param options - Configuration options
+     */
+    toggle(options?: ShowOptions): void;
+    /**
+     * Register a handler for async content loading
+     * @param handler - Async content handler function
+     * @param options - Handler options (once: whether to load only once)
+     */
+    onBeforeOpen(handler: AsyncContentHandler, options?: HandlerOptions): void;
+    /**
+     * Show a panel by ID
+     * @param panelId - ID of the panel to show
+     * @param options - Configuration options for this activation
+     */
+    show(panelId: string, options?: ShowOptions): Promise<void>;
+}
+export default PanelSet;

package/dist/types/panelset.element.d.ts

@@ -0,0 +1,4 @@
+export declare class PanelSetElement extends HTMLElement {
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}

package/dist/types/panelset.esm.d.ts

@@ -0,0 +1,6 @@
+export * from './index'
+export {}
+import _default from './index'
+export default _default
+export * from './index'
+export {}

package/dist/types/panelset.types.d.ts

@@ -0,0 +1,89 @@
+import { AutoFocusMode } from './functions/focus.js';
+export interface PanelSetConfig {
+    selector?: string;
+    align?: 'start' | 'end' | 'center';
+    transitions?: boolean | {
+        panels?: boolean;
+        height?: boolean;
+    };
+    /** Enable level-based slide direction. DOM order defines the level
+     *  (later panel = higher). Adds .levelup / .leveldown to the panels so
+     *  CSS can reverse the transform on backward navigation. Default false. */
+    levels?: boolean;
+    /** Make next() / prev() wrap around the ends (last → first, first → last).
+     *  Default false: they stop at the first and last panel. */
+    loop?: boolean;
+    closable?: boolean;
+    closeOnTab?: boolean;
+    /** How PanelSet disables its own verb buttons (data-ps-next/prev/close) at the
+     *  ends of the range. 'aria' (default) toggles aria-disabled and leaves the
+     *  native disabled attribute to the author; 'native' toggles the native
+     *  disabled attribute (PanelSet owns it) and leaves aria-disabled to the
+     *  author. Tab-strip locking is PanelControl's concern and is always aria. */
+    disabledMode?: 'aria' | 'native';
+    loadingHeight?: number;
+    loadingDelay?: number;
+    returnFocus?: boolean;
+    autoFocus?: AutoFocusMode;
+    persist?: boolean;
+    deepLink?: boolean;
+    interruptible?: boolean;
+    manageTriggers?: boolean;
+    manageLabels?: boolean;
+    debug?: boolean;
+}
+export interface ReadyEventDetail {
+    container: HTMLElement;
+    instance: import('./panelset.js').PanelSet;
+}
+export interface BeforeActivateEventDetail {
+    /** ID of the panel about to be activated. */
+    panelId: string;
+    /** The panel about to be activated. */
+    targetPanel: HTMLElement;
+    /** The currently active panel, if any. */
+    outgoingPanel: HTMLElement | null;
+    /** The element that triggered the activation (button/tab), or null when
+     *  called programmatically without an event. */
+    trigger: HTMLElement | null;
+}
+export interface BeforeOpenEventDetail {
+    panelId: string;
+    targetPanel: HTMLElement;
+    outgoingPanel: HTMLElement | null;
+    signal: AbortSignal;
+    /** Underlying mechanism the open awaits; prefer waitUntil(). */
+    promise: Promise<unknown> | null;
+    /** Delay the open until p resolves. May be called more than once (awaits all). */
+    waitUntil(p: Promise<unknown>): void;
+}
+export interface ActivationEventDetail {
+    panelId: string;
+    trigger: HTMLElement | null;
+    outgoingPanel: HTMLElement | null;
+    /** Zero-based index of the activated panel in DOM order. */
+    index: number;
+    /** Total number of panels in the set. */
+    total: number;
+    /** True when the activated panel is the first one. */
+    atStart: boolean;
+    /** True when the activated panel is the last one. */
+    atEnd: boolean;
+}
+export interface ActivationAbortedEventDetail {
+    panelId: string;
+    trigger: HTMLElement | null;
+}
+export interface HandlerOptions {
+    once?: boolean;
+}
+export interface ShowOptions {
+    event?: Event;
+    transition?: boolean;
+    autoFocus?: AutoFocusMode;
+    /** Force the levels slide direction regardless of DOM order. next()/prev()
+     *  set this so a loop wrap slides in the step's direction ('forward' = like
+     *  Next, even when wrapping to an earlier panel). Only affects sets with levels. */
+    direction?: 'forward' | 'backward';
+}
+export type AsyncContentHandler = (targetPanel: HTMLElement, signal: AbortSignal) => Promise<void> | void;

package/dist/types/register.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,16 +1,26 @@
 {
   "name": "panelset",
-  "version": "1.0.7",
+  "version": "1.2.0",
   "description": "Flexible panel management with smooth transitions",
   "type": "module",
-  "main": "./dist/panelset.js",
-  "types": "./dist/index.d.ts",
+  "sideEffects": [
+    "**/*.css",
+    "**/*.scss"
+  ],
+  "main": "./dist/panelset.esm.js",
+  "types": "./dist/types/index.d.ts",
+  "unpkg": "./dist/panelset.js",
+  "jsdelivr": "./dist/panelset.js",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/panelset.js"
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/panelset.esm.js"
+    },
+    "./register": {
+      "types": "./dist/types/register.d.ts",
+      "import": "./dist/register.js"
     },
-    "./dist/*.css": "./dist/*.css"
+    "./style.css": "./dist/panelset.css"
   },
   "files": [
     "dist",
@@ -18,15 +28,17 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "start": "npm run dev",
-    "dev": "vite --config vite.config.docs.js",
-    "build": "npm run clean && npm run build:lib && npm run build:docs && npm run copy-lib",
+    "start": "cd docs && npm start",
+    "dev": "vite",
+    "docs": "cd docs && npm start",
+    "docs:build": "cd docs && npm run build",
+    "docs:preview": "npm run build && cd docs && rm -rf dist && npm run build && npm run preview",
+    "build": "npm run clean && npm run build:lib",
     "build:lib": "vite build",
-    "build:docs": "vite build --config vite.config.docs.js",
-    "copy-lib": "mkdir -p docs/lib && cp -r dist/* docs/lib/",
-    "preview:docs": "npm run build && vite preview --config vite.config.docs.js",
-    "prepublishOnly": "npm run build",
-    "clean": "rm -rf dist docs"
+    "size": "node scripts/size.mjs",
+    "prepack": "npm run build",
+    "clean": "rm -rf dist",
+    "setup": "cd docs && npm install"
   },
   "keywords": [
     "panels",
@@ -38,13 +50,13 @@
   "author": "Martijn De Jongh",
   "license": "MIT",
   "devDependencies": {
-    "@vituum/vite-plugin-pug": "^1.1.0",
+    "@vituum/vite-plugin-pug": "^2.0.1",
     "fast-glob": "^3.3.3",
     "sass": "^1.97.3",
     "terser": "^5.46.0",
     "typescript": "^5.9.3",
-    "vite": "^7.3.1",
-    "vite-plugin-dts": "^4.5.4",
-    "vituum": "^1.2.0"
+    "vite": "^8.0.0",
+    "vite-plugin-dts": "5.0.0-beta.6",
+    "vituum": "^2.0.1"
   }
 }

package/dist/index.d.ts

@@ -1,119 +0,0 @@
-export declare interface ActivationAbortedEventDetail {
-    panelId: string;
-    trigger: HTMLElement | null;
-}
-
-export declare interface ActivationEventDetail {
-    panelId: string;
-    trigger: HTMLElement | null;
-}
-
-export declare type AsyncContentHandler = (targetPanel: HTMLElement, signal: AbortSignal) => Promise<void> | void;
-
-export declare interface BeforeActivateEventDetail {
-    panelId: string;
-    targetPanel: HTMLElement;
-    outgoingPanel: HTMLElement | null;
-    signal: AbortSignal;
-    promise: Promise<void> | null;
-}
-
-export declare interface HandlerOptions {
-    once?: boolean;
-}
-
-declare class PanelSet {
-    static defaults: Required<Omit<PanelSetConfig, 'selector'>>;
-    element: HTMLElement;
-    config: Required<Omit<PanelSetConfig, 'selector'>>;
-    panels: HTMLElement[];
-    activePanel: HTMLElement;
-    panelWrapper: HTMLElement;
-    pendingPanel: HTMLElement;
-    private _openCloseGeneration;
-    private _isLoadingAsync;
-    private _currentAbortController?;
-    static _getDataConfig(element: HTMLElement): Partial<PanelSetConfig>;
-    static _mergeConfig(defaults: Required<Omit<PanelSetConfig, 'selector'>>, dataConfig: Partial<PanelSetConfig>, options: Partial<PanelSetConfig>): Required<Omit<PanelSetConfig, 'selector'>>;
-    /**
-     * Initialize PanelSet instances
-     * @param selectorOrOptions - CSS selector string or config object
-     * @param options - Additional config options (when first param is selector)
-     * @returns Array of PanelSet instances
-     */
-    static init(selectorOrOptions?: string | PanelSetConfig, options?: PanelSetConfig): PanelSet[];
-    constructor(elementOrSelector: HTMLElement | string, options?: PanelSetConfig);
-    private _log;
-    private static _validateElement;
-    private _autoWrapPanels;
-    private _internalInit;
-    private _dispatch;
-    private _getVerticalMetrics;
-    private _measureHeight;
-    private _updateHighestPanel;
-    private _cleanupPanels;
-    private _waitForTransition;
-    private _handleAutoFocus;
-    private _syncAriaWithActivePanel;
-    private _animateOpenClose;
-    /**
-     * Get the ID of the currently active panel
-     * @returns Panel ID or null if no panel is active
-     */
-    getActive(): string | null;
-    /**
-     * Open a closable panelset
-     * @param options - Configuration options
-     */
-    open(options?: ShowOptions): void;
-    /**
-     * Close a closable panelset
-     * @param options - Configuration options
-     */
-    close(options?: ShowOptions): void;
-    /**
-     * Toggle a closable panelset between open and closed
-     * @param options - Configuration options
-     */
-    toggle(options?: ShowOptions): void;
-    /**
-     * Register a handler for async content loading
-     * @param handler - Async content handler function
-     * @param options - Handler options (once: whether to load only once)
-     */
-    onBeforeActivate(handler: AsyncContentHandler, options?: HandlerOptions): void;
-    /**
-     * Show a panel by ID
-     * @param panelId - ID of the panel to show
-     * @param options - Configuration options for this activation
-     */
-    show(panelId: string, options?: ShowOptions): Promise<void>;
-}
-export { PanelSet }
-export default PanelSet;
-
-export declare interface PanelSetConfig {
-    selector?: string;
-    transitions?: boolean | {
-        panels?: boolean;
-        height?: boolean;
-    };
-    closable?: boolean;
-    emptyPanelHeight?: number;
-    loadingDelay?: number;
-    autoFocus?: boolean | 'heading' | 'first' | 'input';
-    debug?: boolean;
-}
-
-export declare interface ReadyEventDetail {
-    container: HTMLElement;
-    instance: PanelSet;
-}
-
-export declare interface ShowOptions {
-    event?: Event;
-    transition?: boolean;
-    autoFocus?: boolean | 'heading' | 'first' | 'input' | ((panel: HTMLElement) => void);
-}
-
-export { }