@axiapps/axi-design 1.25.0 → 1.27.0

package/README.md

@@ -143,6 +143,7 @@ not "what does the system look like". Everything else is
 | `--axi-rail-w` | an `.axi-rail`'s width, for labels longer than the default holds | `208px` | `<aside class="axi-rail" style="--axi-rail-w: 260px">` |
 | `--axi-rail-pad` | the padding inside an `.axi-rail` | `10px` | `<aside class="axi-rail" style="--axi-rail-pad: 6px">` |
 | `--axi-toolbar-pad` | the padding inside an `.axi-toolbar` | `14px` | `<div class="axi-toolbar" style="--axi-toolbar-pad: 4px 7px">` |
+| `--axi-dock-pad` | the padding inside an `.axi-dock` | `12px 16px` | `<div class="axi-dock" style="--axi-dock-pad: 6px 10px">` |
 | `--axi-avatar-size` | the size of an `.axi-avatar` square | `40px` | `<span class="axi-avatar" style="--axi-avatar-size: 28px">MS</span>` |
 | `--axi-modal-width` | the maximum width of an `.axi-modal`, before the viewport clamp | `560px` | `<dialog class="axi-modal" style="--axi-modal-width: 760px">` |
 | `--axi-card-strip` | the colour of `.axi-card--strip`'s top strip | `var(--axi-accent)` | `<a class="axi-card axi-card--strip" style="--axi-card-strip: var(--axi-ok)">` |
@@ -155,6 +156,8 @@ not "what does the system look like". Everything else is
 | `--axi-palette-top` | how far down the screen an `.axi-palette` opens | `12vh` | `<div class="axi-scrim axi-palette" style="--axi-palette-top: 6vh">` |
 | `--axi-menu-width` | width of `.axi-menu__pop` | `310px` | `<div class="axi-menu__pop" style="--axi-menu-width: 380px">` |
 | `--axi-drawer-width` | width of `.axi-drawer` (capped at `100vw`) | `560px` | `<aside class="axi-drawer" style="--axi-drawer-width: 720px">` |
+| `--axi-sheet-top` | where an `.axi-sheet`'s top edge sits, for an app whose own chrome starts above it | `0` | `<div class="axi-sheet" style="--axi-sheet-top: 2.5rem">` |
+| `--axi-sheet-pad` | the padding inside an `.axi-sheet` | `12px 16px` | `<div class="axi-sheet" style="--axi-sheet-pad: 0">` |
 | `--axi-series` | the ink a meter fill, bar, plot line or `.axi-diamond--series` is drawn in | `var(--axi-accent)` | `<span class="axi-meter__fill" style="--axi-series: var(--axi-ok)">` |
 | `--axi-meter-v` | how full one `.axi-meter__fill` is | `0%` | `<span class="axi-meter__fill" style="--axi-meter-v: 62%">` |
 | `--axi-meter-h` | height of a `.axi-meter` | `12px` | `<div class="axi-meter" style="--axi-meter-h: 18px">` |

package/dist/axi.css

@@ -38,8 +38,10 @@
   --axi-surface-raised: #2b313d;
   /* The fill for a surface that FLOATS over content which scrolls behind it:
      the command palette, the menu and picker popovers, the modal, the drawer,
-     the toast, and any .axi-panel--float, .axi-rail--float or
-     .axi-toolbar--float a consumer declares. Holds --axi-surface, because for
+     the toast, every .axi-dock (which is the one surface here that cannot be
+     anything else - docking IS having content scroll under you), and any
+     .axi-panel--float, .axi-rail--float or .axi-toolbar--float a consumer
+     declares. Holds --axi-surface, because for
      a theme whose panels are opaque a floating panel is just a panel and there
      is nothing to decide.
 
@@ -1279,6 +1281,59 @@ textarea.axi-input {
    lives here instead of in a comment in somebody's component. */
 .axi-toolbar--nowrap { flex-wrap: nowrap; }
 
+/* ---------- dock ---------- */
+/* A bar that IS one edge of its scroll container rather than an object standing
+   in the layout: a tray that drops in above a list, an action bar pinned under
+   one. The horizontal counterpart to .axi-rail--flush, and the shape this
+   language was missing - a rail is vertical, and a toolbar stands in the layout
+   with space around it, so every consumer with a full-width edge bar had to
+   write the surface, the single border and the squared ends by hand.
+
+   It drops what says "an object with space around it", for the reasons
+   .axi-rail--flush drops them: no radius, because its two ends are the
+   container's own edges and a corner there is a corner cut out of the page; and
+   no offset block, because a block needs somewhere to fall and this has content
+   on one side and the container's edges on the other three.
+
+   It is on --axi-surface-float unconditionally, with no --float modifier to
+   forget. Every other surface here can be either way - a panel may sit still on
+   the page or be pinned over a scrolling table - but "the content scrolls under
+   it" is the definition of docking rather than a variant of it. A translucent
+   dock is a dock with the list showing through its own buttons on any platform
+   where the blur is unavailable, which is to say on some platform.
+
+   What it does not say is how its contents are arranged or how it is pinned:
+   put an .axi-toolbar's row of controls inside it, or a head above a scrolling
+   body; make it position: sticky or leave it in flow. Those belong to the
+   consumer, and a dock that answered either would be two objects wearing one
+   name. */
+.axi-dock {
+  /* The inline figure is a page gutter and the block figure is a bar's height.
+     They differ on purpose: a dock spans the full width, so its contents have
+     to line up with the content it is docked against, while how tall it stands
+     is its own business. */
+  padding: var(--axi-dock-pad, 12px 16px);
+  background: var(--axi-surface-float);
+  backdrop-filter: var(--axi-surface-filter);
+  /* The seam's colour and style said once, both widths off, and each modifier
+     below turning on the one side it needs. Spelling the whole shorthand twice
+     would put two independent copies of the edge in the file for a theme to
+     change one of. */
+  border: 0;
+  border-block: 0 solid var(--axi-ink-line);
+  border-radius: 0;
+}
+/* The border faces the content, so a dock at the block-start edge draws it on
+   its block-end side. Logical rather than physical, so it survives a vertical
+   writing mode - the same correction .axi-rail--flush took. */
+.axi-dock:not(.axi-dock--end) { border-block-end-width: var(--axi-border-panel); }
+/* The other edge. Unlike .axi-rail--flush, which assumes the leading edge and
+   has no way to ask for the far one, a dock can say which edge it is on -
+   because both cases arrived together: a tray drops in from the top of a list
+   and an action bar is pinned beneath the same list. This is the pair
+   .axi-rail--flush should grow into the day a trailing-edge rail exists. */
+.axi-dock--end { border-block-start-width: var(--axi-border-panel); }
+
 /* ---------- menu popover ---------- */
 /* A disclosure, not a permanent row of controls. The trigger is an .axi-btn
    with aria-expanded; this styles the panel it opens. */
@@ -1594,6 +1649,66 @@ textarea.axi-input {
 }
 .axi-drawer__body { overflow-y: auto; padding: 18px 24px 30px; }
 
+/* ---------- sheet ---------- */
+/* A pane that covers the whole of its containing block: one thing blown up to
+   fill the app, with a way back out. Three names were already close and all
+   three are wrong, so this one is worth its own word.
+
+   Not .axi-modal. A modal is a <dialog> in the top layer with a scrim and the
+   page inert behind it; a sheet is in the page, and the thing it replaces is
+   the view, not the reader's attention.
+
+   Not .axi-drawer--full. A drawer is pinned to three edges with the page live
+   beside it - that live strip is what makes it a drawer, and it is what pays
+   for the float fill, the leading outline and the scrim. Widen a drawer to the
+   fourth edge and every one of those three goes away, which is a different
+   object wearing a modifier, not a wider drawer.
+
+   Not .axi-panel. Rule 3 outlines a raised element and rule 5 gives it a
+   block, and both are claims about an edge: an element pinned to all four
+   sides has no edge on screen to outline, and nothing behind it this language
+   is entitled to cast a shadow on. So a sheet carries no outline, no block and
+   no radius, and nothing raises it - it is the ground with one thing on it.
+
+   Which is why it paints the ground's IMAGE as well as the ground's colour. A
+   sheet is the page for as long as it is open, and a theme that lights the
+   page from a few directions would otherwise have that light blink off every
+   time a reader opened one, then back on when they closed it. `background` in
+   the shorthand, so a theme leaving --axi-ground-image as `none` still gets a
+   clean flat fill and no stray layer.
+
+   No filter either, for the same reason the window has none: there is nothing
+   to see through to. The two knobs are the only things a consumer genuinely
+   cannot know from here - where its top edge is (an app with its own titlebar
+   starts below it) and how much padding its content wants. */
+.axi-sheet {
+  position: fixed;
+  inset: var(--axi-sheet-top, 0) 0 0;
+  /* Its own rung, between the page's sticky chrome and the scrim. Above 40 and
+     41 because a sheet covers the view, and the masthead and the popovers are
+     part of the view; below 50 because a modal or a drawer opened FROM a sheet
+     has to land on top of it, and a sheet is not the kind of thing that gets
+     to win that. */
+  z-index: 45;
+  display: flex;
+  flex-direction: column;
+  overflow-x: hidden;
+  overflow-y: auto;
+  background: var(--axi-ground) var(--axi-ground-image);
+  padding: var(--axi-sheet-pad, 12px 16px);
+}
+/* The heading the sheet opened with, divided from the body by a rule. Rule 8:
+   a line inside a surface separates its parts rather than raising them - and
+   here it is doing the job the outline a sheet does not have would have done,
+   which is to say where the pane's own chrome stops and its content starts. */
+.axi-sheet__head {
+  flex: none;
+  padding-bottom: 10px;
+  border-bottom: var(--axi-border-control) solid var(--axi-ink-line);
+}
+/* The scrolling region under the head. */
+.axi-sheet__body { flex: 1 1 auto; min-height: 0; }
+
 /* ---------- pull-quote ---------- */
 /* A cited quotation. The accent rule down the left is the only place in the
    language where colour marks a block rather than filling a chip - a quote is

package/docs/RULES.md

@@ -490,6 +490,7 @@ instead of joining it.
 | Table corner | 3 | where the two cross |
 | Sticky chrome | 40 | `.axi-mast` |
 | Popovers | 41 | `.axi-menu__pop`, `.axi-picker__pop` |
+| Sheet | 45 | `.axi-sheet` |
 | Scrim | 50 | `.axi-scrim` |
 | Drawer | 51 | `.axi-drawer` |
 | Toasts | 60 | `.axi-toasts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiapps/axi-design",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "description": "The design language for the axi suite — flat and outlined, dark, drawn in saturated ink.",
   "type": "module",
   "license": "MIT",

package/src/shells.css

@@ -309,6 +309,59 @@
    lives here instead of in a comment in somebody's component. */
 .axi-toolbar--nowrap { flex-wrap: nowrap; }
 
+/* ---------- dock ---------- */
+/* A bar that IS one edge of its scroll container rather than an object standing
+   in the layout: a tray that drops in above a list, an action bar pinned under
+   one. The horizontal counterpart to .axi-rail--flush, and the shape this
+   language was missing - a rail is vertical, and a toolbar stands in the layout
+   with space around it, so every consumer with a full-width edge bar had to
+   write the surface, the single border and the squared ends by hand.
+
+   It drops what says "an object with space around it", for the reasons
+   .axi-rail--flush drops them: no radius, because its two ends are the
+   container's own edges and a corner there is a corner cut out of the page; and
+   no offset block, because a block needs somewhere to fall and this has content
+   on one side and the container's edges on the other three.
+
+   It is on --axi-surface-float unconditionally, with no --float modifier to
+   forget. Every other surface here can be either way - a panel may sit still on
+   the page or be pinned over a scrolling table - but "the content scrolls under
+   it" is the definition of docking rather than a variant of it. A translucent
+   dock is a dock with the list showing through its own buttons on any platform
+   where the blur is unavailable, which is to say on some platform.
+
+   What it does not say is how its contents are arranged or how it is pinned:
+   put an .axi-toolbar's row of controls inside it, or a head above a scrolling
+   body; make it position: sticky or leave it in flow. Those belong to the
+   consumer, and a dock that answered either would be two objects wearing one
+   name. */
+.axi-dock {
+  /* The inline figure is a page gutter and the block figure is a bar's height.
+     They differ on purpose: a dock spans the full width, so its contents have
+     to line up with the content it is docked against, while how tall it stands
+     is its own business. */
+  padding: var(--axi-dock-pad, 12px 16px);
+  background: var(--axi-surface-float);
+  backdrop-filter: var(--axi-surface-filter);
+  /* The seam's colour and style said once, both widths off, and each modifier
+     below turning on the one side it needs. Spelling the whole shorthand twice
+     would put two independent copies of the edge in the file for a theme to
+     change one of. */
+  border: 0;
+  border-block: 0 solid var(--axi-ink-line);
+  border-radius: 0;
+}
+/* The border faces the content, so a dock at the block-start edge draws it on
+   its block-end side. Logical rather than physical, so it survives a vertical
+   writing mode - the same correction .axi-rail--flush took. */
+.axi-dock:not(.axi-dock--end) { border-block-end-width: var(--axi-border-panel); }
+/* The other edge. Unlike .axi-rail--flush, which assumes the leading edge and
+   has no way to ask for the far one, a dock can say which edge it is on -
+   because both cases arrived together: a tray drops in from the top of a list
+   and an action bar is pinned beneath the same list. This is the pair
+   .axi-rail--flush should grow into the day a trailing-edge rail exists. */
+.axi-dock--end { border-block-start-width: var(--axi-border-panel); }
+
 /* ---------- menu popover ---------- */
 /* A disclosure, not a permanent row of controls. The trigger is an .axi-btn
    with aria-expanded; this styles the panel it opens. */
@@ -624,6 +677,66 @@
 }
 .axi-drawer__body { overflow-y: auto; padding: 18px 24px 30px; }
 
+/* ---------- sheet ---------- */
+/* A pane that covers the whole of its containing block: one thing blown up to
+   fill the app, with a way back out. Three names were already close and all
+   three are wrong, so this one is worth its own word.
+
+   Not .axi-modal. A modal is a <dialog> in the top layer with a scrim and the
+   page inert behind it; a sheet is in the page, and the thing it replaces is
+   the view, not the reader's attention.
+
+   Not .axi-drawer--full. A drawer is pinned to three edges with the page live
+   beside it - that live strip is what makes it a drawer, and it is what pays
+   for the float fill, the leading outline and the scrim. Widen a drawer to the
+   fourth edge and every one of those three goes away, which is a different
+   object wearing a modifier, not a wider drawer.
+
+   Not .axi-panel. Rule 3 outlines a raised element and rule 5 gives it a
+   block, and both are claims about an edge: an element pinned to all four
+   sides has no edge on screen to outline, and nothing behind it this language
+   is entitled to cast a shadow on. So a sheet carries no outline, no block and
+   no radius, and nothing raises it - it is the ground with one thing on it.
+
+   Which is why it paints the ground's IMAGE as well as the ground's colour. A
+   sheet is the page for as long as it is open, and a theme that lights the
+   page from a few directions would otherwise have that light blink off every
+   time a reader opened one, then back on when they closed it. `background` in
+   the shorthand, so a theme leaving --axi-ground-image as `none` still gets a
+   clean flat fill and no stray layer.
+
+   No filter either, for the same reason the window has none: there is nothing
+   to see through to. The two knobs are the only things a consumer genuinely
+   cannot know from here - where its top edge is (an app with its own titlebar
+   starts below it) and how much padding its content wants. */
+.axi-sheet {
+  position: fixed;
+  inset: var(--axi-sheet-top, 0) 0 0;
+  /* Its own rung, between the page's sticky chrome and the scrim. Above 40 and
+     41 because a sheet covers the view, and the masthead and the popovers are
+     part of the view; below 50 because a modal or a drawer opened FROM a sheet
+     has to land on top of it, and a sheet is not the kind of thing that gets
+     to win that. */
+  z-index: 45;
+  display: flex;
+  flex-direction: column;
+  overflow-x: hidden;
+  overflow-y: auto;
+  background: var(--axi-ground) var(--axi-ground-image);
+  padding: var(--axi-sheet-pad, 12px 16px);
+}
+/* The heading the sheet opened with, divided from the body by a rule. Rule 8:
+   a line inside a surface separates its parts rather than raising them - and
+   here it is doing the job the outline a sheet does not have would have done,
+   which is to say where the pane's own chrome stops and its content starts. */
+.axi-sheet__head {
+  flex: none;
+  padding-bottom: 10px;
+  border-bottom: var(--axi-border-control) solid var(--axi-ink-line);
+}
+/* The scrolling region under the head. */
+.axi-sheet__body { flex: 1 1 auto; min-height: 0; }
+
 /* ---------- pull-quote ---------- */
 /* A cited quotation. The accent rule down the left is the only place in the
    language where colour marks a block rather than filling a chip - a quote is

package/src/tokens.css

@@ -34,8 +34,10 @@
   --axi-surface-raised: #2b313d;
   /* The fill for a surface that FLOATS over content which scrolls behind it:
      the command palette, the menu and picker popovers, the modal, the drawer,
-     the toast, and any .axi-panel--float, .axi-rail--float or
-     .axi-toolbar--float a consumer declares. Holds --axi-surface, because for
+     the toast, every .axi-dock (which is the one surface here that cannot be
+     anything else - docking IS having content scroll under you), and any
+     .axi-panel--float, .axi-rail--float or .axi-toolbar--float a consumer
+     declares. Holds --axi-surface, because for
      a theme whose panels are opaque a floating panel is just a panel and there
      is nothing to decide.