@eunomia/elements 1.0.0-beta.6 → 1.0.0-beta.8

package/dist/components/navigation/sidebar/sidebar.d.ts

@@ -1,4 +1,5 @@
 import { LitElement, PropertyValues, TemplateResult } from "lit";
+import { EunomiaBreakpoint } from "../../../breakpoints.js";
 /**
  * Tag name of the sidebar component.
  */
@@ -16,6 +17,11 @@ export type EunomiaSidebarCollapseMode = "mini" | "hidden";
  * Where the built-in collapse/expand toggle button renders.
  */
 export type EunomiaSidebarTogglePlacement = "edge" | "inline";
+/**
+ * The sidebar's color scheme.
+ */
+export type EunomiaSidebarTheme = "light" | "dark";
+declare const EunomiaSidebar_base: import("../../../utils/constructor.type.js").Constructor<import("../../../mixins/localizable.mixin.js").LocalizableMixinInterface> & typeof LitElement;
 /**
  * A persistent, non-modal navigation panel that lays out beside page
  * content, sticky by default, so dropping it into a full-height flex
@@ -43,34 +49,40 @@ export type EunomiaSidebarTogglePlacement = "edge" | "inline";
  * @slot footer - Optional footer content, such as a user menu, fixed below the scrollable body. Omitted entirely when nothing is slotted
  * @prop {'start' | 'end'} [position='start'] - Which edge of the layout the sidebar is pinned against
  * @prop {string} heading - An optional heading, rendered as the header slot's fallback content, and used as the accessible name when set
- * @prop {boolean} [collapsible=true] - Whether the built-in toggle button renders at all. The collapse, expand, and toggle methods still work regardless, for driving collapse from elsewhere, such as a page header menu button. Set to false to rely on resizable alone
+ * @prop {'mobile' | 'tablet' | 'laptop' | 'desktop'} hideBelow - Hides the sidebar below this breakpoint, for a layout where another navigation takes over on small screens, such as the toolbar's mobile panel. Also applies before the component loads when sidebar-ssr.css is linked
+ * @attr {'mobile' | 'tablet' | 'laptop' | 'desktop'} hide-below - Hides the sidebar below this breakpoint
+ * @prop {'light' | 'dark'} [theme='light'] - The sidebar's color scheme. Dark uses the inverse surface, for a sidebar on a dark background
+ * @prop {boolean} [collapsible=true] - Whether the built-in toggle button renders at all. The collapse, expand, and toggle methods still work regardless, for driving collapse from elsewhere, such as a page header menu button. Set to false, or the attribute to "false", to rely on resizable alone
  * @prop {'edge' | 'inline'} [togglePlacement='edge'] - Where the built-in toggle button renders: edge floats on the border, and inline sits inside the panel, pinned below the body and footer
  * @attr {'edge' | 'inline'} [toggle-placement='edge'] - Where the built-in toggle button renders: edge floats on the border, and inline sits inside the panel, pinned below the body and footer
  * @prop {'mini' | 'hidden'} [collapseMode='mini'] - The shape the collapsed state takes
  * @attr {'mini' | 'hidden'} [collapse-mode='mini'] - The shape the collapsed state takes
  * @prop {boolean} [collapsed=false] - Whether the sidebar is currently collapsed
- * @prop {string} ariaLabelExpand - The accessible label of the toggle button while collapsed
- * @attr {string} [aria-label-expand='Expand sidebar'] - The accessible label of the toggle button while collapsed
- * @prop {string} ariaLabelCollapse - The accessible label of the toggle button while expanded
- * @attr {string} [aria-label-collapse='Collapse sidebar'] - The accessible label of the toggle button while expanded
- * @prop {boolean} [resizable=true] - Whether the border can be dragged, or, once focused, adjusted with arrow keys, to resize the panel
- * @prop {string} ariaLabelResize - The accessible label of the drag-to-resize border
- * @attr {string} [aria-label-resize='Resize sidebar'] - The accessible label of the drag-to-resize border
- * @fires {ChangeEvent} eunchange - Fired whenever collapsed changes, including as a result of dragging or keyboard-resizing past the collapse threshold. Dragging the border all the way to a full hide is reachable regardless of collapseMode, though keyboard resizing never goes past the mini floor
+ * @prop {string} [expandLabel] - The accessible label of the toggle button while collapsed. Defaults to the localized string for the current locale (English: "Expand sidebar")
+ * @attr {string} [expand-label] - The accessible label of the toggle button while collapsed. Defaults to the localized string for the current locale (English: "Expand sidebar")
+ * @prop {string} [collapseLabel] - The accessible label of the toggle button while expanded. Defaults to the localized string for the current locale (English: "Collapse sidebar")
+ * @attr {string} [collapse-label] - The accessible label of the toggle button while expanded. Defaults to the localized string for the current locale (English: "Collapse sidebar")
+ * @prop {boolean} [resizable=true] - Whether the border can be dragged, or, once focused, adjusted with arrow keys, to resize the panel. Set to false, or the attribute to "false", to turn it off
+ * @prop {string} [resizeLabel] - The accessible label of the drag-to-resize border. Defaults to the localized string for the current locale (English: "Resize sidebar")
+ * @attr {string} [resize-label] - The accessible label of the drag-to-resize border. Defaults to the localized string for the current locale (English: "Resize sidebar")
+ * @fires {ChangeEvent} eunchange - Fired whenever collapsed changes, including as a result of dragging or keyboard-resizing below the mini width. A collapse reached this way takes the shape set by collapseMode, and expanding again returns to --sidebar-width
  * @cssprop [--sidebar-width] - Sets the expanded width of the sidebar, also the floor of the drag-resize range and, once resized, holds the user's chosen width
  * @cssprop [--sidebar-mini-width] - Sets the width of the mini collapsed state, also the floor of the drag-resize range
  * @cssprop [--sidebar-max-width] - Sets the ceiling of the drag-resize range
- * @cssprop [--sidebar-background] - Sets the background color of the sidebar
+ * @cssprop [--sidebar-background] - Sets the background color of the sidebar. Use an opaque color, or transparent to show the background behind the sidebar
  * @cssprop [--sidebar-color] - Sets the text color of the sidebar
  * @cssprop [--sidebar-border-color] - Sets the color of the sidebar's side border
  * @cssprop [--sidebar-padding] - Sets the padding of the header, body, and footer
  * @cssprop [--sidebar-padding-block] - Sets the vertical padding, as one length applied to both sides. Ignored when --sidebar-padding is set
  * @cssprop [--sidebar-padding-inline] - Sets the horizontal padding, as one length applied to both sides. Ignored when --sidebar-padding is set
  * @cssprop [--sidebar-gap] - Sets the gap inside the header and footer rows
+ * @cssprop [--sidebar-toggle-color] - Sets the color of the toggle button
+ * @cssprop [--sidebar-toggle-background-hover] - Sets the background color of the toggle button on hover
+ * @cssprop [--sidebar-resize-handle-delay] - Sets how long the pointer must rest on the border before the resize handle shows. Set to 0 to show it right away
  * @cssprop [--sidebar-transition-duration] - Sets the duration of the collapse and resize transition
  * @element eun-sidebar
  */
-export declare class EunomiaSidebar extends LitElement {
+export declare class EunomiaSidebar extends EunomiaSidebar_base {
     /**
      * Styles to import to the component.
      *
@@ -78,7 +90,7 @@ export declare class EunomiaSidebar extends LitElement {
      * @internal
      * @readonly
      */
-    static readonly styles: import("lit").CSSResult;
+    static readonly styles: import("lit").CSSResult[];
     /**
      * Which edge of the layout the sidebar is pinned against — decides which
      * edge the border, toggle button, and resize handle render on : always
@@ -86,6 +98,20 @@ export declare class EunomiaSidebar extends LitElement {
      * @default start
      */
     position: EunomiaSidebarPosition;
+    /**
+     * Hides the sidebar below this breakpoint (`display: none`), for a layout
+     * where another navigation takes over on small screens, such as
+     * `eun-toolbar`'s mobile panel, which switches at `tablet` by default.
+     * A plain `@media` switch in the stylesheet, mirrored in
+     * `sidebar-ssr.css`, so it applies from first paint.
+     */
+    hideBelow?: EunomiaBreakpoint;
+    /**
+     * The sidebar's color scheme : `dark` uses the inverse surface, the same
+     * one `eun-toolbar`'s own `theme="dark"` does.
+     * @default light
+     */
+    theme: EunomiaSidebarTheme;
     /**
      * Optional heading text, rendered as the `header` slot's fallback
      * content, and used as the accessible name (there's no dialog to
@@ -97,7 +123,9 @@ export declare class EunomiaSidebar extends LitElement {
      * for where) ; `collapse()`/`expand()`/`toggleCollapse()` work regardless,
      * for driving collapse from elsewhere (e.g. a page header menu button) —
      * set this to `false` to drop the built-in button entirely and rely on
-     * `resizable` (dragging the border past the mini floor) alone.
+     * `resizable` (dragging the border past the mini floor) alone. The
+     * attribute value `"false"` turns it off too (see {@link
+     * defaultTrueConverter}).
      * @default true
      */
     collapsible: boolean;
@@ -124,27 +152,28 @@ export declare class EunomiaSidebar extends LitElement {
     collapsed: boolean;
     /**
      * Accessible label of the toggle button while collapsed (offering to expand it).
-     * @default Expand sidebar
+     * Falls back to the localized string for the current locale when unset.
      */
-    ariaLabelExpand: string;
+    expandLabel?: string;
     /**
      * Accessible label of the toggle button while expanded (offering to collapse it).
-     * @default Collapse sidebar
+     * Falls back to the localized string for the current locale when unset.
      */
-    ariaLabelCollapse: string;
+    collapseLabel?: string;
     /**
      * Whether the border can be dragged (or, once focused, adjusted with the
      * arrow keys) to resize the panel between `--sidebar-mini-width` and
      * `--sidebar-max-width`. Independent of `collapsible`, which only
-     * controls the discrete toggle button.
+     * controls the discrete toggle button. The attribute value `"false"`
+     * turns it off too (see {@link defaultTrueConverter}).
      * @default true
      */
     resizable: boolean;
     /**
      * Accessible label of the drag-to-resize border.
-     * @default Resize sidebar
+     * Falls back to the localized string for the current locale when unset.
      */
-    ariaLabelResize: string;
+    resizeLabel?: string;
     /**
      * The drag-to-resize border.
      * @internal
@@ -170,8 +199,7 @@ export declare class EunomiaSidebar extends LitElement {
     private dragStartWidth;
     /**
      * The last *unclamped* width computed during a drag, used on release to
-     * decide whether the drag went far enough past the mini floor to snap
-     * into a full `collapse-mode="hidden"` collapse.
+     * decide whether the drag went below the mini floor and collapses.
      * @internal
      */
     private lastRawWidth;
@@ -184,13 +212,6 @@ export declare class EunomiaSidebar extends LitElement {
      * @internal
      */
     private dragStartCollapsed;
-    /**
-     * Whether `draggedHidden` was set right before the current drag started
-     * — compared against the final state at release for the same reason
-     * `dragStartCollapsed` is.
-     * @internal
-     */
-    private dragStartHidden;
     /**
      * Whether `pointermove` actually fired at least once since the current
      * `pointerdown` — a plain click on the resize handle (no movement)
@@ -205,18 +226,18 @@ export declare class EunomiaSidebar extends LitElement {
      */
     private dragging;
     /**
-     * Whether a drag has forced the panel fully hidden (width `0`, border
-     * transparent) regardless of `collapse-mode` — `collapse-mode="mini"`'s
-     * own collapsed state normally floors at `--sidebar-mini-width`, but a
-     * drag that goes well past that floor toward zero can still reach a full
-     * hide, matching what `collapse-mode="hidden"` already looks like.
-     * Reflected so CSS can force `--_width`/`border-color` to win over
-     * collapse-mode's own (otherwise fixed) collapsed-state rule. Cleared by
-     * any discrete collapse()/expand()/toggleCollapse() (button or API),
-     * which always takes precedence over a lingering drag state.
+     * Whether the resize handle shows its highlight and resize cursor : set
+     * once the pointer has rested on the border for
+     * `--sidebar-resize-handle-delay`, or right away on `pointerdown`, so
+     * merely crossing the border on the way to the content doesn't flash it.
+     * @internal
+     */
+    private resizeHandleArmed;
+    /**
+     * The pending timer arming {@link resizeHandleArmed}, if any.
      * @internal
      */
-    private draggedHidden;
+    private resizeHandleArmTimer?;
     /**
      * The width, in px, applied by the current (or most recent) drag/keyboard
      * resize — `undefined` until the panel has been manually resized at
@@ -256,6 +277,11 @@ export declare class EunomiaSidebar extends LitElement {
      * @param changed the changed properties.
      */
     protected updated(changed: PropertyValues): void;
+    /**
+     * Lifecycle hook called when the element is disconnected from the DOM.
+     * Clears a pending resize handle arming timer.
+     */
+    disconnectedCallback(): void;
     /**
      * Collapses the sidebar.
      */
@@ -276,6 +302,13 @@ export declare class EunomiaSidebar extends LitElement {
      * @private
      */
     private setCollapsed;
+    /**
+     * Drops the width a drag or keyboard resize applied, so the next expand
+     * returns to `--sidebar-width` instead of the narrow width the resize
+     * collapsed from.
+     * @private
+     */
+    private forgetResizedWidth;
     /**
      * Reads a length custom property off the host's computed style, parsed
      * as a px number.
@@ -318,16 +351,16 @@ export declare class EunomiaSidebar extends LitElement {
      * `--sidebar-width` override, so a drag tracks the pointer immediately
      * rather than waiting on Lit's render cycle) and reactively (via
      * `liveWidthPx`, so `#resize-handle`'s `aria-valuenow` stays in sync).
-     * Also clears `collapsed`/`draggedHidden` without dispatching : while
-     * either reflects, its CSS rule sets `--_width` directly and would
-     * otherwise ignore every live update below — `settleWidth`/
-     * `settleCollapsedState` restore the correct final truth (and their one
-     * authoritative `eunchange`) once the interaction ends.
+     * Also clears `collapsed` without dispatching : while it reflects, its
+     * CSS rule sets `--_width` directly and would otherwise ignore every live
+     * update below — `settleWidth`/`settleCollapsedState` restore the correct
+     * final truth (and their one authoritative `eunchange`) once the
+     * interaction ends.
      *
      * @param px the requested width, in px.
-     * @param floor the minimum to clamp to — the mini width by default
-     * (used by keyboard resizing, which never fully hides the panel), or
-     * `0` during a live drag so it can visually approach a full hide.
+     * @param floor the minimum to clamp to — the mini width by default, or
+     * `0` during a `collapse-mode="hidden"` drag so it can visually approach
+     * a full hide.
      * @private
      */
     private applyWidth;
@@ -335,9 +368,10 @@ export declare class EunomiaSidebar extends LitElement {
      * Reconciles `collapsed` once a *keyboard* resize ends, comparing the
      * interaction's start and end states so exactly one `eunchange` fires
      * for a genuine transition — and none at all for a resize that never
-     * crossed the mini floor. Never settles into `draggedHidden` : keyboard
-     * resizing intentionally can't fully hide the panel (see
-     * `handleResizeKeydown`).
+     * crossed the mini floor. Only `collapse-mode="mini"` collapses here :
+     * under `hidden`, collapsing would hide the panel entirely, which stays
+     * the toggle button's job (see `handleResizeKeydown`). A collapse forgets
+     * the resized width, so the next expand returns to `--sidebar-width`.
      *
      * @param widthPx the final width the interaction landed on.
      * @param wasCollapsed whether the sidebar was collapsed when the
@@ -346,21 +380,35 @@ export declare class EunomiaSidebar extends LitElement {
      */
     private settleCollapsedState;
     /**
-     * Reconciles both `collapsed` and `draggedHidden` once a *drag* resize
-     * ends. Three outcomes, based on where the (unclamped) drag landed :
-     * above the mini floor, free width ; below it but not by much, a
-     * magnetic snap up to exactly the mini width ; well below it, a full
-     * hide (`draggedHidden`) regardless of `collapse-mode` — dragging is a
-     * deliberate enough gesture that reaching zero should always be
-     * reachable, unlike keyboard stepping. Fires exactly one `eunchange` iff
-     * either flag actually changed from where the interaction started.
+     * Reconciles `collapsed` once a *drag* resize ends : a drag that lands
+     * below the mini floor collapses into whichever shape `collapse-mode`
+     * sets (the icon rail for `mini`, a full hide for `hidden`), and forgets
+     * the dragged width so the next expand returns to `--sidebar-width`.
+     * Anywhere else keeps the dragged width, clamped to the resize range.
+     * Fires exactly one `eunchange` iff `collapsed` actually changed from
+     * where the interaction started.
      *
      * @param rawWidth the final unclamped width the drag landed on.
      * @param wasCollapsed whether `collapsed` was set when the drag started.
-     * @param wasHidden whether `draggedHidden` was set when the drag started.
      * @private
      */
     private settleWidth;
+    /**
+     * Arms the resize handle once the pointer has rested on the border for
+     * `--sidebar-resize-handle-delay` (300ms by default).
+     * @private
+     */
+    private readonly handleResizePointerEnter;
+    /**
+     * Disarms the resize handle as soon as the pointer leaves the border.
+     * @private
+     */
+    private readonly handleResizePointerLeave;
+    /**
+     * Clears {@link resizeHandleArmed} and its pending timer, if any.
+     * @private
+     */
+    private disarmResizeHandle;
     /**
      * Starts a drag-resize : captures the pointer on the handle itself (so
      * subsequent `pointermove`/`pointerup` keep firing there even once the
@@ -373,10 +421,10 @@ export declare class EunomiaSidebar extends LitElement {
     /**
      * Tracks an in-progress drag-resize, applying the live width as the
      * pointer moves. Direction is flipped for `position="end"`, where
-     * dragging left (toward the panel) grows it. Tracks all the way down to
-     * `0` (not just the mini floor) so the panel visually approaches a full
-     * hide as the drag continues — `handleResizePointerUp` decides whether
-     * it actually settles there.
+     * dragging left (toward the panel) grows it. Under `collapse-mode="mini"`
+     * the panel stops at the mini floor, the narrowest it can ever be ; under
+     * `hidden` it tracks all the way down to `0`, previewing the full hide —
+     * `handleResizePointerUp` decides whether it actually collapses.
      *
      * @param event the pointermove event.
      * @private
@@ -384,8 +432,7 @@ export declare class EunomiaSidebar extends LitElement {
     private readonly handleResizePointerMove;
     /**
      * Ends a drag-resize : a plain click (no movement) is a no-op ; see
-     * `settleWidth` for how the final width resolves into `collapsed`/
-     * `draggedHidden`.
+     * `settleWidth` for how the final width resolves into `collapsed`.
      *
      * @param event the pointerup/pointercancel event.
      * @private
@@ -491,3 +538,4 @@ declare global {
         [EunomiaSidebarTagName]: EunomiaSidebar;
     }
 }
+export {};