@dereekb/dbx-web 13.10.7 → 13.10.8

package/lib/action/snackbar/_snackbar.scss

@@ -4,6 +4,11 @@
 
 // MARK: Mixin
 @mixin core() {
+  /// @dbx-utility action-snackbar
+  /// @intent action-snackbar layout — flex row used by the `<dbx-action-snackbar>` host so the message and trailing button sit on one line
+  /// @role layout
+  /// @component DbxActionSnackbarComponent
+  /// @scope component-class
   .dbx-action-snackbar {
     display: flex;
     align-items: center;

package/lib/button/_button.scss

@@ -10,6 +10,10 @@ $big-button-height: 46px; // 33% bigger
 // MARK: Mixin
 @mixin core() {
   // increases the height of the mat-mdc-button
+  /// @dbx-utility button-big
+  /// @intent enlarge the inner `mat-mdc-button` height to 46px (33% taller than default)
+  /// @role layout
+  /// @see-also button-wide
   .dbx-button-big,
   .dbx-button-large {
     .mdc-button.mat-mdc-button {
@@ -19,6 +23,9 @@ $big-button-height: 46px; // 33% bigger
 
   // Neutral hover/pressed/focus state layer instead of the primary-colored default.
   // Apply to buttons with custom background colors where the primary tint looks wrong.
+  /// @dbx-utility button-neutral-interaction-color
+  /// @intent neutralize Material's hover/pressed/focus/ripple state layer to `--mat-sys-on-surface` — use on buttons with a custom background where the primary-tinted state-layer would clash
+  /// @role state
   .dbx-button-neutral-interaction-color {
     .mdc-button,
     &.mdc-button {
@@ -41,6 +48,10 @@ $big-button-height: 46px; // 33% bigger
     }
   }
 
+  /// @dbx-utility button-wide
+  /// @intent stretch the inner `.dbx-button` to a 120px minimum width (still capped by parent)
+  /// @role layout
+  /// @see-also button-grow
   .dbx-button-wide {
     .dbx-button {
       min-width: 120px;
@@ -48,6 +59,10 @@ $big-button-height: 46px; // 33% bigger
     }
   }
 
+  /// @dbx-utility button-wrap-group
+  /// @intent group of buttons that wrap onto multiple rows — adds 6px right + bottom spacing between `<dbx-button>` / `<dbx-anchor>` / `<button>` / `<dbx-icon-button>` siblings
+  /// @role layout
+  /// @see-also button-column, dbx-flex-bar
   .dbx-button-wrap-group {
     > dbx-button,
     > dbx-anchor {
@@ -84,6 +99,10 @@ $big-button-height: 46px; // 33% bigger
     }
   }
 
+  /// @dbx-utility grow-button
+  /// @intent stretch the `<dbx-button>` (and its inner `.dbx-button`) to the full width of its parent
+  /// @role layout
+  /// @see-also button-wide, dbx-w100
   .dbx-grow-button {
     width: 100%;
 
@@ -92,6 +111,10 @@ $big-button-height: 46px; // 33% bigger
     }
   }
 
+  /// @dbx-utility button-spacer
+  /// @intent right-padding spacer between buttons or beside a button — 6px right padding (use `<dbx-button-spacer>` to insert one inline)
+  /// @role spacing
+  /// @see-also chip-spacer, icon-spacer
   .dbx-button-spacer {
     padding-right: $button-spacer-width;
   }
@@ -100,6 +123,10 @@ $big-button-height: 46px; // 33% bigger
     margin-right: $button-spacer-width;
   }
 
+  /// @dbx-utility button-column
+  /// @intent vertical button stack — flex column with 6px bottom spacing between children, left-aligned by default (compose with `.dbx-button-column-center` to center)
+  /// @role flex
+  /// @see-also button-wrap-group, dbx-flex-column
   .dbx-button-column {
     display: flex;
     flex-direction: column;

package/lib/error/_error.scss

@@ -6,6 +6,11 @@ $error-message-button-margin: 12px;
 
 // MARK: Mixin
 @mixin core() {
+  /// @dbx-utility error
+  /// @intent error row — `<dbx-error>` body that lays out an icon + message in a centered flex row with an 8px top inset
+  /// @role layout
+  /// @component DbxErrorComponent
+  /// @scope component-class
   .dbx-error {
     padding-top: $error-padding;
     display: flex;

package/lib/extension/pdf/_pdf.scss

@@ -3,21 +3,6 @@
 
 // MARK: Mixin
 @mixin core() {
-  .dbx-pdf-merge-editor {
-    display: block;
-  }
-
-  .dbx-pdf-merge-editor-upload {
-    display: block;
-    margin-bottom: 12px;
-  }
-
-  .dbx-pdf-merge-editor-error {
-    margin: 8px 0;
-    padding: 8px 12px;
-    border-radius: var(--mat-sys-corner-small);
-  }
-
   .dbx-pdf-merge-editor-actions {
     display: flex;
     align-items: center;
@@ -25,33 +10,34 @@
     margin-top: 12px;
   }
 
-  .dbx-pdf-merge-editor-spacer {
-    flex: 1;
+  // Slot upload
+  .dbx-pdf-merge-editor-file-upload-header {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    min-height: 0;
+  }
+
+  .dbx-pdf-merge-editor-file-upload-header:not(:empty) {
+    margin-bottom: 6px;
   }
 
-  .dbx-pdf-merge-editor-count {
-    margin-right: 8px;
+  .dbx-pdf-merge-editor-file-upload-label {
+    font-weight: 500;
   }
 
-  .dbx-pdf-preview {
-    display: block;
-    width: 100%;
-    height: 100%;
+  .dbx-pdf-merge-editor-file-upload-entries {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    margin-top: 6px;
   }
 
   .dbx-pdf-preview-frame {
-    display: block;
-    width: 100%;
-    height: 100%;
     min-height: 480px;
   }
 
   // List
-  .dbx-pdf-merge-list-empty {
-    padding: 16px;
-    text-align: center;
-  }
-
   .dbx-pdf-merge-list-items {
     display: flex;
     flex-direction: column;
@@ -59,10 +45,6 @@
   }
 
   // Entry
-  .dbx-pdf-merge-entry {
-    display: block;
-  }
-
   .dbx-pdf-merge-entry-row {
     display: flex;
     align-items: center;
@@ -95,38 +77,16 @@
     cursor: grabbing;
   }
 
-  .dbx-pdf-merge-entry-icon {
+  .dbx-pdf-merge-entry-icon,
+  .dbx-pdf-merge-entry-remove {
     flex-shrink: 0;
   }
 
-  .dbx-pdf-merge-entry-icon-error {
-    color: var(--mat-sys-error);
-  }
-
-  .dbx-pdf-merge-entry-info {
-    flex: 1;
-    min-width: 0;
-  }
-
-  .dbx-pdf-merge-entry-name {
-    overflow: hidden;
-    white-space: nowrap;
-    text-overflow: ellipsis;
-  }
-
   .dbx-pdf-merge-entry-meta {
     display: flex;
     gap: 8px;
   }
 
-  .dbx-pdf-merge-entry--error .dbx-pdf-merge-entry-status {
-    color: var(--mat-sys-error);
-  }
-
-  .dbx-pdf-merge-entry-remove {
-    flex-shrink: 0;
-  }
-
   // CDK animations
   .cdk-drop-list-dragging .dbx-pdf-merge-entry-row:not(.cdk-drag-placeholder) {
     transition: transform 250ms cubic-bezier(0, 0, 0.2, 1);

package/lib/interaction/dialog/_dialog.scss

@@ -16,6 +16,11 @@ $dbx-dialog-content-close-right-offset: $dbx-dialog-content-close-edge-padding;
     color: var(--mat-sys-on-surface);
   }
 
+  /// @dbx-utility dialog-content
+  /// @intent dialog body — `<dbx-dialog-content>` host that wraps mat-dialog content with the standard 18px inset; compose with `.dbx-dialog-content-with-header` to reserve room for a sticky header, `.dbx-dialog-content-100` to fill the dialog height, or `.dbx-p0` to strip the inset
+  /// @role layout
+  /// @component DbxDialogContentComponent
+  /// @scope component-class
   .dbx-dialog-content {
     display: block;
     padding: $mat-dialog-container-padding;

package/lib/interaction/popover/_popover.scss

@@ -7,6 +7,11 @@ $dbx-popover-header-height: 48px;
 
 // MARK: Mixin
 @mixin core() {
+  /// @dbx-utility popover-container
+  /// @intent popover surface — `<dbx-popover>` host that paints the `--mat-sys-surface` background with the `--mat-sys-corner-medium` border-radius
+  /// @role layout
+  /// @component DbxPopoverComponent
+  /// @scope component-class
   .dbx-popover-container {
     background: var(--mat-sys-surface);
     border-radius: var(--mat-sys-corner-medium, 12px);

package/lib/interaction/popup/_popup.scss

@@ -11,6 +11,11 @@ $dbx-popup-border-radius: 4px;
 
 // MARK: Mixin
 @mixin core() {
+  /// @dbx-utility popup-content
+  /// @intent popup body — `<dbx-popup-content>` host that caps the inner content at `app-height` and clips overflow; pair with `.dbx-popup-content-container` for the inner scroll region and `.dbx-popup-controls` for the header strip
+  /// @role layout
+  /// @component DbxPopupContentComponent
+  /// @scope component-class
   .dbx-popup-content {
     box-sizing: border-box;
     overflow: hidden;

package/lib/interaction/prompt/_prompt.scss

@@ -12,6 +12,10 @@ $dbx-popup-controls-height: 33px;
     }
   }
 
+  /// @dbx-utility prompt-box
+  /// @intent centered prompt panel — auto-margined max-width box with a 40px inset (compose with `.elevate` to lift it with elevation 2)
+  /// @role layout
+  /// @see-also content-box, content-elevate
   .dbx-prompt-box {
     margin: auto;
     padding: 40px;

package/lib/interaction/upload/_upload.scss

@@ -2,6 +2,10 @@
 
 // Sections
 @mixin core() {
+  .dbx-file-upload-area {
+    position: relative;
+  }
+
   .dbx-file-upload-area-content {
     display: flex;
     flex-direction: column;
@@ -18,10 +22,18 @@
     align-items: center;
   }
 
+  /// @dbx-utility file-upload-area-rounded
+  /// @intent circle modifier for `.dbx-file-upload-area` — `border-radius: 50%`
+  /// @role layout
+  /// @see-also file-upload-area-square
   .dbx-file-upload-area-rounded {
     border-radius: 50%;
   }
 
+  /// @dbx-utility file-upload-area-square
+  /// @intent rounded-square modifier for `.dbx-file-upload-area` — uses `--mat-sys-corner-medium` (override via `--dbx-file-upload-square-container-shape`)
+  /// @role layout
+  /// @see-also file-upload-area-rounded
   .dbx-file-upload-area-square {
     border-radius: var(--dbx-file-upload-square-container-shape, var(--mat-sys-corner-medium));
   }
@@ -31,12 +43,13 @@
   }
 
   .dbx-file-upload-area-content-hint {
-    position: relative;
-    top: -24px;
+    position: absolute;
+    bottom: 8px;
     left: 0;
     right: 0;
     text-align: center;
     user-select: none;
+    pointer-events: none;
   }
 
   .dbx-file-upload-area-content {

package/lib/layout/avatar/_avatar.scss

@@ -5,6 +5,12 @@ $icon-to-avatar-size-ratio: 0.65;
 
 // MARK: Mixin
 @mixin core() {
+  /// @dbx-utility avatar-view
+  /// @intent fixed-size avatar surface — `<dbx-avatar-view>` body that shows a square 64px avatar (configurable via `--dbx-avatar-size`) and scales the inner `mat-icon` to 65% of that size
+  /// @role layout
+  /// @component DbxAvatarViewComponent
+  /// @scope component-class
+  /// @see-also avatar-small, avatar-large, avatar-view-circle, avatar-view-square
   .dbx-avatar-view {
     position: relative;
     display: inline-flex;
@@ -25,6 +31,11 @@ $icon-to-avatar-size-ratio: 0.65;
     display: none;
   }
 
+  /// @dbx-utility avatar-small
+  /// @intent small avatar wrapper — overrides the inner `.dbx-avatar-view` size to 32px (configurable via `--dbx-avatar-small-size`)
+  /// @role layout
+  /// @parent avatar-view
+  /// @see-also avatar-view, avatar-large
   .dbx-avatar-small .dbx-avatar-view {
     width: var(#{theming.$dbx-avatar-small-size-var}, 32px);
     height: var(#{theming.$dbx-avatar-small-size-var}, 32px);
@@ -36,6 +47,11 @@ $icon-to-avatar-size-ratio: 0.65;
     }
   }
 
+  /// @dbx-utility avatar-large
+  /// @intent large avatar wrapper — overrides the inner `.dbx-avatar-view` size to 128px (configurable via `--dbx-avatar-large-size`)
+  /// @role layout
+  /// @parent avatar-view
+  /// @see-also avatar-view, avatar-small
   .dbx-avatar-large .dbx-avatar-view {
     width: var(#{theming.$dbx-avatar-large-size-var}, 128px);
     height: var(#{theming.$dbx-avatar-large-size-var}, 128px);
@@ -62,10 +78,20 @@ $icon-to-avatar-size-ratio: 0.65;
     height: 100%;
   }
 
+  /// @dbx-utility avatar-view-circle
+  /// @intent circle modifier for `.dbx-avatar-view` — `border-radius: 50%`
+  /// @role layout
+  /// @parent avatar-view
+  /// @see-also avatar-view, avatar-view-square
   .dbx-avatar-view-circle {
     border-radius: 50%;
   }
 
+  /// @dbx-utility avatar-view-square
+  /// @intent rounded-square modifier for `.dbx-avatar-view` — uses `--mat-sys-corner-medium` (override via `--dbx-avatar-square-container-shape`)
+  /// @role layout
+  /// @parent avatar-view
+  /// @see-also avatar-view, avatar-view-circle
   .dbx-avatar-view-square {
     border-radius: var(--dbx-avatar-square-container-shape, var(--mat-sys-corner-medium));
   }

package/lib/layout/bar/_bar.scss

@@ -19,6 +19,10 @@ $bar-fixed-height: 40px;
     max-height: $content-navbar-height;
   }
 
+  /// @dbx-utility bar
+  /// @intent compact horizontal bar — centered flex row with body-small typography (used for status/info strips)
+  /// @role layout
+  /// @see-also dbx-bar-background, dbx-bar-fixed-height, dbx-flex-bar
   .dbx-bar {
     box-sizing: border-box;
     padding: $bar-vertical-padding;
@@ -32,11 +36,19 @@ $bar-fixed-height: 40px;
     color: var(--mat-sys-on-surface);
   }
 
+  /// @dbx-utility bar-background
+  /// @intent paint a `.dbx-bar` with the `--mat-sys-surface-container` background
+  /// @role layout
+  /// @see-also dbx-bar
   .dbx-bar-background {
     background: var(--mat-sys-surface-container);
     color: var(--mat-sys-on-surface);
   }
 
+  /// @dbx-utility bar-fixed-height
+  /// @intent pin a `.dbx-bar` to a fixed 40px height with overflow clipped
+  /// @role layout
+  /// @see-also dbx-bar
   .dbx-bar-fixed-height {
     height: $bar-fixed-height;
     overflow: hidden;
@@ -46,21 +58,36 @@ $bar-fixed-height: 40px;
   // Color classes applied by DbxPagebarComponent based on the color input.
   // Uses Material toolbar CSS tokens for background and text color.
   // Background uses color-mix with surface-container for consistent dark-mode contrast.
+  /// @dbx-utility bar-primary
+  /// @intent paint a `mat-toolbar`/`.dbx-pagebar` with the `--dbx-primary-color` palette via Material's toolbar tokens
+  /// @role layout
+  /// @see-also dbx-bar-accent, dbx-bar-warn
   .dbx-bar-primary {
     --mat-toolbar-container-background-color: var(--dbx-primary-color);
     --mat-toolbar-container-text-color: var(--dbx-primary-color-contrast);
   }
 
+  /// @dbx-utility bar-accent
+  /// @intent paint a `mat-toolbar`/`.dbx-pagebar` with the `--dbx-accent-color` palette via Material's toolbar tokens
+  /// @role layout
+  /// @see-also dbx-bar-primary, dbx-bar-warn
   .dbx-bar-accent {
     --mat-toolbar-container-background-color: var(--dbx-accent-color);
     --mat-toolbar-container-text-color: var(--dbx-accent-color-contrast);
   }
 
+  /// @dbx-utility bar-warn
+  /// @intent paint a `mat-toolbar`/`.dbx-pagebar` with the `--dbx-warn-color` palette via Material's toolbar tokens
+  /// @role layout
+  /// @see-also dbx-bar-primary, dbx-bar-accent
   .dbx-bar-warn {
     --mat-toolbar-container-background-color: var(--dbx-warn-color);
     --mat-toolbar-container-text-color: var(--dbx-warn-color-contrast);
   }
 
+  /// @dbx-utility pagebar-hide
+  /// @intent hide the direct-child `.dbx-pagebar` and reset the `--dbx-pagebar-height` layout token to `0px` so child sidenav heights recalculate (nested sidenav pagebars are restored)
+  /// @role state
   .dbx-pagebar-hide {
     // Reset pagebar height for layout calculations (page height = app height - navbar height)
     #{$pagebar-height-var}: 0px;

package/lib/layout/block/_block.scss

@@ -10,6 +10,10 @@ $two-block-top-height-var: --dbx-two-block-top-height;
     height: 100%;
   }
 
+  /// @dbx-utility two-block-content
+  /// @intent two-block stack content area — fixed-height region whose `.dbx-two-block-bottom` child fills the remaining height after a 50px (default) `.dbx-two-block-top`. Override the top height via `--dbx-two-block-top-height`.
+  /// @role layout
+  /// @see-also two-column
   .dbx-two-block-content {
     height: 100%;
     #{$two-block-top-height-var}: $two-block-top-height-init-height;

package/lib/layout/column/_column.scss

@@ -8,6 +8,9 @@ $two-columns-right-padding-size: 6px;
 
 // MARK: Mixin
 @mixin core() {
+  /// @dbx-utility two-column
+  /// @intent two-column page layout — fixed-width left column with elevated right content area
+  /// @role layout
   .dbx-two-column {
     height: 100%;
     max-width: 100%;

package/lib/layout/content/_content.scss

@@ -24,15 +24,27 @@ $dbx-content-pit-floating-button-margin: 8px;
 $dbx-border-opacity-default: 20%;
 
 @mixin core() {
+  /// @dbx-utility content-border
+  /// @intent dashed-border content frame — pads the inner content and draws a 3px dashed border via `--dbx-border-color` / `--dbx-border-opacity`
+  /// @role layout
+  /// @see-also dbx-content-elevate, dbx-content-pit
   .dbx-content-border {
     padding: $content-border-inner-padding;
   }
 
+  /// @dbx-utility content-elevate
+  /// @intent padded content surface lifted with elevation 2 — combines inner padding with a Material elevation shadow
+  /// @role layout
+  /// @see-also dbx-content-border, dbx-content-pit
   .dbx-content-elevate {
     padding: $content-border-inner-padding;
     @include theming.elevation(2);
   }
 
+  /// @dbx-utility content-box
+  /// @intent centered box — auto-margined max-width content surface with a `padding-4` inset and `2vh` bottom margin (compose with `.dbx-content-box-wide` to remove the max-width)
+  /// @role layout
+  /// @see-also dbx-content-container, dbx-prompt-box
   .dbx-content-box {
     margin: auto;
     padding: $box-padding;
@@ -44,10 +56,19 @@ $dbx-border-opacity-default: 20%;
     }
   }
 
+  /// @dbx-utility content-pit
+  /// @intent recessed surface pit — `--mat-sys-surface-container` background with a `padding-4` inset, used to visually nest content (e.g. logs, JSON, quoted blocks)
+  /// @role layout
+  /// @see-also dbx-content-pit-rounded, dbx-content-pit-scrollable, dbx-content-border, dbx-content-elevate
   .dbx-content-pit {
     padding: $pit-padding;
   }
 
+  /// @dbx-utility content-pit-rounded
+  /// @intent rounded modifier for `.dbx-content-pit` — applies the `theming.$dbx-content-pit-rounded-border-radius` corner radius
+  /// @role layout
+  /// @parent content-pit
+  /// @see-also dbx-content-pit
   .dbx-content-pit-rounded {
     border-radius: theming.$dbx-content-pit-rounded-border-radius;
   }
@@ -56,6 +77,11 @@ $dbx-border-opacity-default: 20%;
     opacity: 0.66; // increase opacity slightly to make it easier to read against background
   }
 
+  /// @dbx-utility content-pit-scrollable
+  /// @intent scrollable modifier for `.dbx-content-pit` — caps height at `theming.$dbx-content-pit-scrollable-max-height` and forces `overflow-y: scroll` for long inner content
+  /// @role layout
+  /// @parent content-pit
+  /// @see-also dbx-content-pit
   .dbx-content-pit-scrollable {
     max-height: theming.$dbx-content-pit-scrollable-max-height;
     max-width: 100%;
@@ -103,6 +129,9 @@ $dbx-border-opacity-default: 20%;
     padding: 0 2px; // Override padding
   }
 
+  /// @dbx-utility content-container
+  /// @intent centered, padded content container with width-class and padding-class modifiers
+  /// @role layout
   .dbx-content-container {
     margin: auto;
     padding: 0 $content-container-padding;

package/lib/layout/flex/_flex.scss

@@ -6,6 +6,10 @@ $dbx-flex-group-columns-count: 6;
 
 // MARK: Mixin
 @mixin core() {
+  /// @dbx-utility flex-bar
+  /// @intent horizontal action bar — flex row that scrolls horizontally before wrapping
+  /// @role flex
+  /// @see-also dbx-flex-center, dbx-flex-fill
   .dbx-flex-bar {
     display: flex;
     align-items: center;
@@ -23,17 +27,50 @@ $dbx-flex-group-columns-count: 6;
     --mat-fab-small-touch-target-size: 40px;
   }
 
+  /// @dbx-utility flex-center
+  /// @intent center children both axes via flex
+  /// @role flex
+  /// @see-also dbx-flex-bar, dbx-flex-column
   .dbx-flex-center {
     display: flex;
     align-items: center;
     justify-content: center;
   }
 
+  /// @dbx-utility flex-column
+  /// @intent vertical flex stack — children laid out top-to-bottom
+  /// @role flex
+  /// @see-also dbx-flex-bar
   .dbx-flex-column {
     display: flex;
     flex-direction: column;
   }
 
+  /// @dbx-utility flex-fill
+  /// @intent fill remaining space inside a flex container
+  /// @role flex
+  /// @see-also dbx-flex-fill-0
+  /// @anti-use Use dbx-flex-fill-0 when the fill child must also truncate or otherwise shrink below its intrinsic width.
+  .dbx-flex-fill {
+    flex: 1;
+  }
+
+  /// @dbx-utility flex-fill-0
+  /// @intent fill remaining flex space and allow the child to truncate (`min-width: 0` overrides the default flex-item `min-width: auto`)
+  /// @role flex
+  /// @see-also dbx-flex-fill, dbx-text-truncate
+  // `min-width: 0` lets the flex item shrink below its content's intrinsic
+  // width — required for child truncation (e.g. `.dbx-text-truncate`) to
+  // actually clip inside the fill region.
+  .dbx-flex-fill-0 {
+    flex: 1;
+    min-width: 0;
+  }
+
+  /// @dbx-utility flex-group
+  /// @intent responsive flex grid — children opt into widths via .dbx-flex-1 ... .dbx-flex-6
+  /// @role flex
+  /// @see-also dbx-flex-bar
   .dbx-flex-group {
     display: flex;
     flex-wrap: wrap;