@aquera/nile-elements 2.0.9 → 2.0.11

package/src/nile-app-shell/nile-app-shell.css.ts

@@ -6,29 +6,32 @@
  */
 
 import { css } from 'lit';
+import { utilityControlStyles } from '../internal/app-shell-utility-control-styles';
 
-/**
- * AppShell CSS.
- *
- * One grid, two columns, one flex row. The grid owns the banner row, the
- * optional shell-wide top bar, the side-nav track and the content column. The
- * content column is a flex row holding the content container, the optional
- * aside and — when docked — the AI panel. Nothing else in an app sets these
- * boxes.
- */
+/** AppShell CSS: a grid of banner, top bar, side-nav track and content column, whose flex row holds the container, aside and docked AI panel. */
 export const styles = css`
   :host {
-    /* Geometry. Values come from design tokens wherever one exists; the bare
-       pixels are shell geometry with no matching token. */
-    --nile-app-shell-side-nav-width: 260px;
-    --nile-app-shell-side-nav-rail-width: 64px;
-    --nile-app-shell-gutter: var(--nile-spacing-md, var(--ng-spacing-md));
+    /* Geometry: design tokens where one exists, bare pixels where none does. */
+    /* The nav track mirrors nile-side-bar's own width expressions (enterprise 240/70, NxtGen 296/68); keep in step with nile-side-bar.css.ts. */
+    --nile-app-shell-side-nav-width: var(
+      --nile-width-240px,
+      var(--ng-spacing-296, 240px)
+    );
+    --nile-app-shell-side-nav-rail-width: var(
+      --nile-width-70px,
+      var(--ng-spacing-68, 70px)
+    );
+    --nile-app-shell-gutter: var(--nile-spacing-xs, var(--ng-spacing-xs));
     --nile-app-shell-content-padding: var(
       --nile-spacing-3xl,
       var(--ng-spacing-3xl)
     );
-    --nile-app-shell-top-bar-height: 56px;
-    --nile-app-shell-tabs-height: 48px;
+    --nile-app-shell-top-bar-height: 68px;
+    /* The panel header keeps its own height, distinct from the page header. */
+    --nile-app-shell-panel-header-height: 56px;
+    --nile-app-shell-tabs-height: 33px;
+    /* The leading app icon is its own 20px size, not the 32px utility box. */
+    --nile-app-shell-app-icon-size: 20px;
     --nile-app-shell-panel-width: 480px;
     --nile-app-shell-panel-min-width: 360px;
     --nile-app-shell-aside-width: 320px;
@@ -36,9 +39,10 @@ export const styles = css`
     --nile-app-shell-content-min-width: 640px;
     --nile-app-shell-min-width: 768px;
     --nile-app-shell-centered-width: 824px;
+    /* Both tokens are 32px; the literal is the floor with no theme sheet loaded. */
     --nile-app-shell-utility-size: var(
       --nile-spacing-4xl,
-      var(--ng-spacing-4xl)
+      var(--ng-spacing-4xl, 32px)
     );
     --nile-app-shell-radius: var(--nile-radius-xl, var(--ng-radius-2xl));
     --nile-app-shell-duration: var(
@@ -78,8 +82,7 @@ export const styles = css`
     height: 100dvh;
   }
 
-  /* Effective rail state, set by the component: the user's preference, or a
-     forced rail at narrow widths. */
+  /* Effective rail state: the user's preference, or a forced rail when narrow. */
   :host([rail]) {
     --_side-nav-track: var(--nile-app-shell-side-nav-rail-width);
   }
@@ -88,10 +91,19 @@ export const styles = css`
     --_side-nav-track: 0px;
   }
 
+  /* The Description axis: a present description adds the 8px its second line occupies. */
+  :host([has-description]) {
+    --nile-app-shell-top-bar-height: 76px;
+  }
+
   /* The top bar compresses before the content does. */
   @media (max-height: 600px) {
     :host {
-      --nile-app-shell-top-bar-height: 48px;
+      --nile-app-shell-top-bar-height: 56px;
+    }
+
+    :host([has-description]) {
+      --nile-app-shell-top-bar-height: 64px;
     }
   }
 
@@ -119,13 +131,12 @@ export const styles = css`
     display: none;
   }
 
-  /*
-   * The nav and the page share one surface, and the shell owns the track
-   * width, so a slotted sidebar fills the track and drops its own background
-   * and edge. Set --nile-app-shell-side-nav-bg to put a surface back.
-   */
+  /* A slotted sidebar fills the shell-owned track and drops its own surface and edge; set --nile-app-shell-side-nav-bg to restore one. */
+  /* width is deliberately not !important: the 100% lets a raw <nav> or nile-app-shell-side-nav fill the track, while a slotted
+     nile-side-bar sizes itself from the same tokens the track reads (see the :host geometry block). Tests 21/22 in
+     nile-app-shell-regions.test.ts lock the two together; change both or neither. */
   ::slotted([slot='side-nav']) {
-    width: 100% !important;
+    width: 100%;
     height: 100%;
     background: var(--nile-app-shell-side-nav-bg, transparent) !important;
     border-right: var(--nile-app-shell-side-nav-border, 0) !important;
@@ -140,19 +151,19 @@ export const styles = css`
     min-width: 0;
     gap: var(--nile-app-shell-gutter);
     padding: var(--nile-app-shell-gutter);
+    /* Flush against the nav track; the gutter insets the other three sides. */
+    padding-inline-start: 0;
     box-sizing: border-box;
   }
 
+  /* With no nav track there is nothing to sit flush against, so the start edge takes the gutter too. */
+  :host(:not([has-side-nav])) .content-section {
+    padding-inline-start: var(--nile-app-shell-gutter);
+  }
+
   .container {
     box-sizing: border-box;
-    /*
-     * The floor is the flex basis, not a min-width: a hard min-width cannot
-     * yield, so the row overflows and :host's overflow:hidden clips the
-     * regions after it. As a basis the container holds the floor while there
-     * is room and gives way when there is not. The shell keeps a docked panel
-     * off the row until it fits (see _dockRequirement), so the give-way path
-     * is the last resort, not the usual one.
-     */
+    /* The floor is the flex basis, not a min-width, so the container yields instead of overflowing the clipped row. */
     flex: 1 1 var(--nile-app-shell-content-min-width);
     display: flex;
     flex-direction: column;
@@ -160,24 +171,15 @@ export const styles = css`
     overflow: hidden;
     background: var(--nile-colors-white-base, var(--ng-colors-bg-secondary));
     border: var(--nile-border-width-1, var(--ng-border-width-1)) solid
-      var(--nile-colors-neutral-400, var(--ng-colors-border-secondary));
+      var(--nile-colors-neutral-500, var(--ng-colors-border-primary));
     border-radius: var(--nile-app-shell-radius);
     box-shadow: var(--nile-box-shadow-none, var(--ng-shadow-none));
-    /*
-     * The container — not the viewport — is the sizing context for page
-     * content. See the content-container note below for querying it.
-     */
+    /* The container, not the viewport, is the sizing context for page content. */
     container-type: inline-size;
     container-name: nile-content;
   }
 
-  /*
-   * Container queries cannot cross a shadow boundary: a rule in the page's
-   * stylesheet cannot see a container declared in here. The
-   * content-container attribute moves the context onto the slotted page root instead, so page CSS can
-   * write an @container nile-content query. It brings layout containment with
-   * it, so it is opt-in.
-   */
+  /* content-container moves the size query context onto the slotted page root so page CSS can query nile-content; opt-in as it brings containment. */
   :host([content-container]) slot:not([name])::slotted(*) {
     container-type: inline-size;
     container-name: nile-content;
@@ -201,12 +203,7 @@ export const styles = css`
     padding-inline: var(--nile-app-shell-content-padding);
   }
 
-  /* Inside the container the bar carries the rule that separates it from the
-     page body; spanning the shell it carries the container's edge instead. */
-  .container > .top-bar {
-    border-bottom: var(--nile-border-width-1, var(--ng-border-width-1)) solid
-      var(--nile-colors-neutral-400, var(--ng-colors-border-secondary));
-  }
+  /* The header bar draws no bottom rule in any variant; the only divider comes from the tab rail (see .tabs). */
 
   .shell-top-bar {
     grid-area: top-bar;
@@ -230,6 +227,171 @@ export const styles = css`
     flex: 1 1 auto;
   }
 
+  /* The title block: the header's own heading, the Leading axis and the badge; renders before the top-bar slot. */
+  .title-area {
+    display: flex;
+    /* Top-aligned, not centred: the leading element belongs to the title's row, not the title-plus-description stack. */
+    align-items: flex-start;
+    gap: var(--nile-spacing-md, var(--ng-spacing-md));
+    min-width: 0;
+  }
+
+  /* The leading line box: exactly the page title's line height, centring whatever leading control sits in it. */
+  .leading {
+    flex: 0 0 auto;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--nile-spacing-md, var(--ng-spacing-md));
+    min-height: var(--nile-line-height-medium, var(--ng-line-height-text-md));
+  }
+
+  .title-stack {
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    gap: var(--nile-spacing-xxs, var(--ng-spacing-xxs));
+    min-width: 0;
+  }
+
+  .title-row {
+    display: flex;
+    align-items: center;
+    gap: var(--nile-spacing-md, var(--ng-spacing-md));
+    min-width: 0;
+  }
+
+  .page-title {
+    margin: 0;
+    min-width: 0;
+    font-family: var(--nile-font-family-serif, var(--ng-font-family-body));
+    font-size: var(--nile-type-scale-3, var(--ng-font-size-text-md));
+    line-height: var(--nile-line-height-medium, var(--ng-line-height-text-md));
+    font-weight: var(--nile-font-weight-medium, var(--ng-font-weight-semibold));
+    color: var(--nile-colors-dark-900, var(--ng-colors-text-primary-900));
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  .description {
+    margin: 0;
+    min-width: 0;
+    font-family: var(--nile-font-family-serif, var(--ng-font-family-body));
+    font-size: var(--nile-type-scale-1, var(--ng-font-size-text-xs));
+    line-height: var(--nile-line-height-xsmall, var(--ng-line-height-text-xs));
+    font-weight: var(--nile-font-weight-regular, var(--ng-font-weight-regular));
+    color: var(--nile-colors-dark-500, var(--ng-colors-text-tertiary-600));
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  /* The badge sits on the title row and never shrinks the title away; each surface token pairs a Nile name with its NxtGen equivalent. */
+  .badge {
+    flex: 0 0 auto;
+    display: inline-flex;
+    align-items: center;
+    padding-inline: var(--nile-spacing-md, var(--ng-spacing-md));
+    padding-block: var(--nile-spacing-xxs, var(--ng-spacing-xxs));
+    border: var(--nile-border-width-1, var(--ng-border-width-1)) solid
+      var(
+        --nile-colors-neutral-400,
+        var(--ng-componentcolors-utility-gray-200)
+      );
+    border-radius: var(--nile-radius-full, var(--ng-radius-full));
+    background: var(
+      --nile-colors-neutral-100,
+      var(--ng-componentcolors-utility-gray-50)
+    );
+    color: var(
+      --nile-colors-dark-500,
+      var(--ng-componentcolors-utility-gray-700)
+    );
+    font-family: var(--nile-font-family-serif, var(--ng-font-family-body));
+    font-size: var(--nile-type-scale-1, var(--ng-font-size-text-xs));
+    line-height: var(--nile-line-height-xsmall, var(--ng-line-height-text-xs));
+    font-weight: var(--nile-font-weight-medium, var(--ng-font-weight-medium));
+    white-space: nowrap;
+  }
+
+  /* Leading=Back: drawn as a breadcrumb label; the shell owns no history, so pressing it only emits nile-header-back. */
+  .back {
+    flex: 0 0 auto;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--nile-spacing-xs, var(--ng-spacing-xs));
+    margin: 0;
+    padding: 0;
+    border: 0;
+    background: none;
+    cursor: pointer;
+    font-family: var(--nile-font-family-serif, var(--ng-font-family-body));
+    font-size: var(--nile-type-scale-3, var(--ng-font-size-text-md));
+    line-height: var(--nile-line-height-medium, var(--ng-line-height-text-md));
+    font-weight: var(--nile-font-weight-medium, var(--ng-font-weight-semibold));
+    color: var(--nile-colors-dark-500, var(--ng-colors-text-tertiary-600));
+  }
+
+  .back:hover {
+    color: var(--nile-colors-dark-900, var(--ng-colors-text-primary-900));
+  }
+
+  .crumb-divider {
+    flex: 0 0 auto;
+    display: inline-flex;
+    align-items: center;
+    color: var(--nile-colors-dark-500, var(--ng-colors-fg-quaternary-400));
+  }
+
+  /* Leading=AppIcon: a 20px block before the title; the page slots the mark, the shell owns the box, surface and radius. */
+  .app-icon {
+    position: relative;
+    flex: 0 0 auto;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--nile-app-shell-app-icon-size);
+    height: var(--nile-app-shell-app-icon-size);
+    border-radius: var(--nile-radius-sm, var(--ng-radius-sm));
+    overflow: hidden;
+  }
+
+  /* The slotted mark fills the wrapper edge to edge, clipped to the box. */
+  .app-icon slot::slotted(*) {
+    width: 100%;
+    height: 100%;
+    display: block;
+    object-fit: cover;
+  }
+
+  /* The wrapper takes no fill; the rim is a white-12% gradient drawn as a masked ::before, with literal mask fallbacks for the nxtgen-only tokens. */
+  .app-icon::before {
+    content: '';
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
+    pointer-events: none;
+    z-index: 1;
+    background: linear-gradient(
+      180deg,
+      rgb(255 255 255 / 12%) 0%,
+      rgb(255 255 255 / 0%) 100%
+    );
+    mask: var(
+      --ng-mask-rim,
+      linear-gradient(#000 0 0) content-box,
+      linear-gradient(#000 0 0)
+    );
+    mask-composite: var(--ng-mask-composite-exclude, exclude);
+    padding: 1.4px;
+  }
+
+  :host(:not([leading='app-icon'])) .app-icon,
+  :host(:not([leading='back'])) .back,
+  :host(:not([leading='back'])) .crumb-divider {
+    display: none;
+  }
+
   .top-bar-actions {
     display: flex;
     align-items: center;
@@ -237,25 +399,12 @@ export const styles = css`
     margin-inline-start: auto;
   }
 
-  /*
-   * An empty flex item still takes the row's gap before it, which pulls the
-   * bar's content 16px short of the padding edge and leaves a sliver of bare
-   * container at the end of the header. Nothing in the group, no box.
-   */
+  /* Hidden when empty, so an empty group's gap does not pull the bar's content short of the padding edge. */
   :host(:not([has-top-bar-actions]):not([has-ask])) .top-bar-actions {
     display: none;
   }
 
-  /*
-   * The Ask button. The one control in the bar the shell renders itself: it
-   * turns on the panel being mounted and it calls openPanel(), neither of
-   * which slotted markup can reach.
-   *
-   * It is a stock <nile-button variant="primary">: the shell sets no surface,
-   * radius, height or type of its own, so the button's appearance — and its
-   * focus ring, hover, disabled and loading states — stays the component's.
-   * The only rule here is the flex behaviour it needs as a top-bar item.
-   */
+  /* The Ask button: a stock <nile-button variant="primary"> the shell renders itself; the only rule here is its flex behaviour as a top-bar item. */
   .ask {
     flex: 0 0 auto;
   }
@@ -278,12 +427,9 @@ export const styles = css`
     gap: var(--nile-spacing-lg, var(--ng-spacing-lg));
   }
 
-  /*
-   * Lands the 24px glyph box, not nile-button's 38px circle, on the
-   * container's 24px origin: (38 - 24) / 2 = 7.
-   */
+  /* Lands the 20px glyph box, not the 32px utility circle, on the 24px origin: (32 - 20) / 2 = 6. */
   .nav-toggle {
-    margin-inline-start: -7px;
+    margin-inline-start: -6px;
   }
 
   .rule {
@@ -296,13 +442,14 @@ export const styles = css`
     );
   }
 
+  /* ------------------------------------------------------- utility controls */
+
+  /* The shell's own icon controls (nav toggle, panel back and close): the shared utility-control recipe. */
+  ${utilityControlStyles}
+
   /* --------------------------------------------------------------- tab strip */
 
-  /*
-   * Hoisted out of the scroller so it never scrolls away. It sits flush under
-   * the top bar — the header carries no bottom rule of its own, so the two read
-   * as one block of chrome, with the single rule living at the strip's bottom.
-   */
+  /* Hoisted out of the scroller so it never scrolls away; sits flush under the top bar and carries the header block's single bottom rule. */
   .tabs {
     box-sizing: border-box;
     flex: 0 0 auto;
@@ -310,6 +457,7 @@ export const styles = css`
     align-items: stretch;
     gap: var(--nile-spacing-xs, var(--ng-spacing-xs));
     min-width: 0;
+    /* A floor, not a fixed box: the strip is as tall as the row it holds plus its rule. */
     min-height: var(--nile-app-shell-tabs-height);
     padding-inline: var(--nile-app-shell-content-padding);
     /* The strip carries the rule for the whole header block. */
@@ -319,14 +467,32 @@ export const styles = css`
     scrollbar-width: none;
   }
 
+  /* The header tab's 0/4/12/4 padding composes the 32px row; the 12px bottom gives the active indicator its band, set via the group's public padding hook. */
+  ::slotted([slot='tabs']) {
+    --nile-nav-tab-padding: var(--nile-spacing-none, var(--ng-spacing-none))
+      var(--nile-spacing-xs, var(--ng-spacing-xs))
+      var(--nile-spacing-lg, var(--ng-spacing-lg))
+      var(--nile-spacing-xs, var(--ng-spacing-xs));
+  }
+
   .tabs::-webkit-scrollbar {
     display: none;
   }
 
-  :host(:not([has-tabs])) .tabs {
+  :host(:not([has-tabs])) .tabs,
+  :host([notabs]) .tabs {
     display: none;
   }
 
+  /* A slotted nile-nav-tab-group drops its own track (--track-width:0 on the host) and is bottom-aligned so its indicator sits on the region's single rule. */
+  /* Scoped to the group, not the slot, so bare tab controls are not stretched to an equal share of the strip. */
+  ::slotted(nile-nav-tab-group[slot='tabs']) {
+    --track-width: 0px;
+    flex: 1 1 auto;
+    min-width: 0;
+    align-self: flex-end;
+  }
+
   /* ------------------------------------------------------------------- main */
 
   .main {
@@ -336,7 +502,9 @@ export const styles = css`
     flex-direction: column;
     min-height: 0;
     overflow: auto;
+    /* Top and sides only: the page runs to the container's bottom edge. */
     padding: var(--nile-app-shell-content-padding);
+    padding-block-end: 0;
   }
 
   .main:focus {
@@ -354,13 +522,7 @@ export const styles = css`
 
   /* Centred when short, scrolls from the top when tall. */
   :host([content-align='centered']) .main-inner {
-    /*
-     * width:100% + max-width leaves free space for the auto inline margins to
-     * split; dropping the width would let the auto margins cancel the flex
-     * stretch and shrink-wrap the column to its widest child. The block margins
-     * centre it while it is short and compute to 0 once it is taller, so a tall
-     * page scrolls from the top rather than clipping.
-     */
+    /* width:100% + max-width leaves space for the auto margins to centre it while short, and scroll from the top when tall. */
     width: 100%;
     max-width: var(--nile-app-shell-centered-width);
     margin: auto;
@@ -370,8 +532,7 @@ export const styles = css`
 
   .aside {
     box-sizing: border-box;
-    /* Gives before the page does, down to its own floor, for the same reason
-       the panel does: the page is the last region to be asked for room. */
+    /* Gives before the page does, down to its own floor. */
     flex: 0 1 var(--nile-app-shell-aside-width);
     min-width: var(--nile-app-shell-aside-min-width);
     display: flex;
@@ -393,13 +554,7 @@ export const styles = css`
 
   .panel {
     box-sizing: border-box;
-    /*
-     * The panel pushes the page, it never covers it, so it has to be able to
-     * give a little: full width while the row can afford it, then shrinking to
-     * its min. Here the floor can be a real min-width — the container's floor
-     * is a flex basis that yields all the way, so the row still cannot
-     * overflow into :host's clip once the panel stops giving.
-     */
+    /* The panel pushes the page rather than covering it: full width while the row affords it, shrinking to a real min-width floor. */
     flex: 0 1 var(--nile-app-shell-panel-width);
     width: var(--nile-app-shell-panel-width);
     min-width: var(--nile-app-shell-panel-min-width);
@@ -453,13 +608,28 @@ export const styles = css`
     flex: 0 0 auto;
     display: flex;
     align-items: center;
-    gap: var(--nile-spacing-lg, var(--ng-spacing-lg));
-    height: var(--nile-app-shell-top-bar-height);
-    padding-inline: var(--nile-spacing-xl, var(--ng-spacing-xl));
+    gap: var(--nile-spacing-md, var(--ng-spacing-md));
+    height: var(--nile-app-shell-panel-header-height);
+    padding-inline: var(--nile-spacing-3xl, var(--ng-spacing-3xl));
     border-bottom: var(--nile-border-width-1, var(--ng-border-width-1)) solid
       var(--nile-colors-neutral-400, var(--ng-colors-border-secondary));
   }
 
+  /* The back control for a panel sub-view; stands where the brand mark does in the root view. */
+  .panel-back {
+    flex: 0 0 auto;
+    margin-inline-start: -6px;
+  }
+
+  /* Mirrors the back control's offset on the end edge: the 20px glyph, not the 32px circle, lands on the padding line. */
+  .panel-close {
+    margin-inline-end: -6px;
+  }
+
+  :host([panelback]) .panel-mark {
+    display: none;
+  }
+
   .panel-heading {
     display: flex;
     align-items: center;
@@ -506,7 +676,8 @@ export const styles = css`
     flex: 1 1 auto;
     min-height: 0;
     overflow: auto;
-    padding: var(--nile-spacing-xl, var(--ng-spacing-xl));
+    /* 16 under the header, 24 on the sides and bottom. */
+    padding: var(--nile-spacing-xl, var(--ng-spacing-xl)) var(--nile-spacing-3xl, var(--ng-spacing-3xl)) var(--nile-spacing-3xl, var(--ng-spacing-3xl));
     display: flex;
     flex-direction: column;
     gap: var(--nile-spacing-xl, var(--ng-spacing-xl));
@@ -514,7 +685,7 @@ export const styles = css`
 
   .panel-footer {
     flex: 0 0 auto;
-    padding: var(--nile-spacing-xl, var(--ng-spacing-xl));
+    padding: var(--nile-spacing-xl, var(--ng-spacing-xl)) var(--nile-spacing-3xl, var(--ng-spacing-3xl)) var(--nile-spacing-3xl, var(--ng-spacing-3xl));
     border-top: var(--nile-border-width-1, var(--ng-border-width-1)) solid
       var(--nile-colors-neutral-400, var(--ng-colors-border-secondary));
   }