contain-css-svelte 1.2.3 → 1.4.0

package/dist/layout/Sidebar.svelte.d.ts

@@ -6,6 +6,63 @@ declare const Sidebar: import("svelte").Component<ContainProps<HTMLAttributes<HT
     left?: boolean;
     right?: boolean;
     children?: Snippet;
+    /**
+     * Float the panel *over* the page content at every width instead of
+     * widening the aside and pushing the content aside. Narrow/compact
+     * screens already overlay, so this only changes the wide layout.
+     *
+     * An overlay sidebar also takes the compact layout's affordance: a
+     * button that opens a sheet, starting shut. The grab-bar rail is for a
+     * panel that lives in the layout -- floating one over the content and
+     * asking someone to grab it is strange, and a panel that starts open on
+     * top of the content is worse.
+     */
+    overlay?: boolean;
+    /**
+     * Pin the sheet to the viewport while the page scrolls past it, instead
+     * of stretching it to the height of whatever it sits beside.
+     *
+     * Without it, an open sheet is as tall as its row -- right beside a
+     * short card, wrong beside a fifty-row table, where the top of the
+     * panel scrolls away and anything at its foot ends up off the bottom of
+     * the page. With it, the sheet (and its button) stick at
+     * `--sidebar-sheet-top` and stop growing at `--sidebar-sheet-max-height`,
+     * scrolling their own content past that.
+     *
+     * Applies wherever the sheet does: any `overlay` sidebar, and any
+     * sidebar in the compact layout. The wide rail is unaffected. Like any
+     * `position: sticky`, it needs every ancestor up to the scrolling one to
+     * leave `overflow` alone.
+     */
+    sticky?: boolean;
+    /**
+     * The shape of the sheet's toggle button (the sheet is what any
+     * `overlay` sidebar, and any sidebar in the compact layout, uses).
+     *
+     * - `"tab"` (default): the corners on the side it attaches to are
+     *   square, so it reads as fastened to that edge -- the page edge while
+     *   shut, the panel's edge while open. Right against a page edge.
+     * - `"button"`: rounded all round like any other button, for a sheet
+     *   that does not sit against an edge -- beside a table, inside page
+     *   padding -- where a half-flat tab looks broken.
+     *
+     * Per-state control, if you need it, is by variable:
+     * `--sidebar-sheet-expand-edge-radius` (the shut button) and
+     * `--sidebar-sheet-collapse-edge-radius` (the open one), both falling
+     * back to `--sidebar-sheet-edge-radius`.
+     */
+    sheetButton?: "tab" | "button";
+    /**
+     * Whether the sidebar is showing its panel. Bindable, so a caller can
+     * drive the sidebar from a button of their own:
+     * `<Sidebar bind:open />`.
+     *
+     * Left `undefined` (the default) the sidebar keeps its per-layout
+     * defaults -- the wide rail starts open, the compact sheet starts
+     * closed -- and the built-in toggles set it from there. Once it holds a
+     * boolean, that boolean wins in both layouts.
+     */
+    open?: boolean | undefined;
     /**
      * Accessible name for the button that opens the sidebar on narrow
      * screens, and for the one that collapses it once open. What the sidebar
@@ -14,6 +71,6 @@ declare const Sidebar: import("svelte").Component<ContainProps<HTMLAttributes<HT
      */
     expandLabel?: string;
     collapseLabel?: string;
-}, SidebarStyleProps & StyleProps<readonly ["bg", "fg", "fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing", "textAlign", "textTransform", "textDecoration", "fontVariant"]>>, {}, "">;
+}, SidebarStyleProps & StyleProps<readonly ["bg", "fg", "fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing", "textAlign", "textTransform", "textDecoration", "fontVariant"]>>, {}, "open">;
 type Sidebar = ReturnType<typeof Sidebar>;
 export default Sidebar;

package/dist/layout/SidebarContainer.svelte

@@ -0,0 +1,198 @@
+<script lang="ts">import { elementProps } from "../util";
+import { COLOR_VARS, PADDING_VARS, RADIUS_VARS, } from "../styleProps";
+let { right = false, children, class: className, ...restProps } = $props();
+const SIDEBAR_CONTAINER_VARS = [
+    ...COLOR_VARS,
+    ...PADDING_VARS,
+    ...RADIUS_VARS,
+];
+const el = $derived(elementProps(restProps, "sidebar-container", [
+    ...SIDEBAR_CONTAINER_VARS,
+    "width",
+    "height",
+    "gap",
+]));
+</script>
+
+<div class={["sidebar-container", className]} class:right {...el}>
+  {@render children?.()}
+</div>
+
+<style>/* Per-level heading (h1-h6) box/typography properties, resolved to PRIVATE,
+   inheriting custom properties (--_h1-color, --_h2-font-size, etc) rather than
+   assigned directly to a matched h1-h6 selector. Nothing in this file matches
+   an actual heading element anymore -- see typography-context.css (vars/), which
+   is the single, global, :where()-scoped rule that actually reads these vars
+   and applies them to real elements. That split is what lets a component
+   nested arbitrarily deep (through <article>, <Tile>, whatever) still get the
+   nearest ancestor's heading styling: these are ordinary inherited custom
+   properties, so DOM proximity decides which component's values apply, not
+   selector specificity or stylesheet order. See AGENTS-INTERNAL.md. */
+/* All six heading levels' context vars in one call -- what every
+   "typography container" component (Container, Card, Tile, TextLayout, ...)
+   includes on itself once, alongside the shared --_heading-* vars below. */
+/* Shared prose-measure group: p, blockquote, dl, ul, ol. li/dt/dd don't get
+   their own vars -- they're never wider than their ul/ol/dl parent's own
+   max-width box, so they're already bounded for free by ordinary block
+   layout, not by anything selector-based reaching them individually. */
+/* p specifically also gets the fuller typography-props-bare treatment
+   (paragraph-prefixed), which -- same as in the original selector-based
+   version -- is declared/consumed AFTER the shared prose vars above, so it
+   wins for whichever properties both groups set. */
+/* The first paragraph in a typography context (p:first-of-type, or a p right
+   after a heading) gets its own, slightly different treatment -- larger lede
+   text, no top margin. Structural matching (:first-of-type, `h1 + p`) still
+   has to happen where the real element is, in the global consumer rule; only
+   the VALUES move to context vars here. */
+/* Logical, not top/bottom/left/right: margin-block/margin-inline already take
+   one value (both sides equal) or two (start end), so there is no separate
+   "which side" prop to remember and no 4-value shorthand order to get wrong.
+   Defaults to 0 on purpose -- unlike padding-props above, a margin that
+   appeared by default on every consumer would be a silent layout change the
+   day this mixin got added to a new component. Callers opt in with an actual
+   value. (Container does not use this mixin: it wants --gap/auto as its
+   defaults, which do not fit the "0 unless asked" contract here.) */
+/* The width at or below which a Sidebar swaps its grab-bar rail for the sheet
+   affordance -- a floating button that opens a panel over the content.
+
+   Page has to agree with Sidebar about this, because Page is what floats the
+   aside out of flow and reserves the strip of padding the sheet button sits
+   in. They used to disagree: Sidebar switched at 512px and Page at 600px,
+   which left a band between 513 and 600 where Page had already lifted the
+   aside out of the layout while the Sidebar inside it was still showing a
+   rail -- a grab bar floating on top of the content, which is the affordance
+   we deliberately avoid everywhere else.
+
+   One definition, used by both, so they cannot drift again. */
+/* Warning: because we define a fallback
+  media query, the media query can override the container
+  if we stack a bunch of these in a row and aren't thoughtful about the order.
+  Put min-width queries *after* max-width queries so that smaller
+  container queries don't get their styles overridden by large media queries.
+  */
+/* Convenience groupings */
+.sidebar-container {
+  --link-bg: var(--sidebar-container-link-bg, var(--surface-link-bg, inherit));
+  --link-fg: var(--sidebar-container-link-fg, var(--surface-link-fg, inherit));
+  --_bg-mix-color: var(--sidebar-container-bg-mix-color, var(--surface-bg-mix-color, var(--bg-mix-color, transparent)));
+  --_bg-mix-amount: var(--sidebar-container-bg-mix-amount, var(--surface-bg-mix-amount, var(--bg-mix-amount, 0%)));
+  --_fg-mix-color: var(--sidebar-container-fg-mix-color, var(--surface-fg-mix-color, var(--fg-mix-color, transparent)));
+  --_fg-mix-amount: var(--sidebar-container-fg-mix-amount, var(--surface-fg-mix-amount, var(--fg-mix-amount, 0%)));
+  --_bg-base: var(--sidebar-container-bg, var(--surface-bg, var(--bg, unset)));
+  --_fg-base: var(--sidebar-container-fg, var(--surface-fg, var(--fg, unset)));
+  --_background-color: color-mix(
+    in srgb,
+    var(--_bg-base),
+    var(--_bg-mix-color) var(--_bg-mix-amount)
+  );
+  --_color: color-mix(
+    in srgb,
+    var(--_fg-base),
+    var(--_fg-mix-color) var(--_fg-mix-amount)
+  );
+  --muted-color: var(--muted-color-override, var(--_background-color));
+  --primary-text-fg: var(
+    --primary-text-fg-override,
+    color-mix(
+      in srgb,
+      var(--_color),
+      var(--primary-color)
+        var(--primary-text-amount, var(--text-amount, 50%))
+    )
+  );
+  --secondary-text-fg: var(
+    --secondary-text-fg-override,
+    color-mix(
+      in srgb,
+      var(--_color),
+      var(--secondary-color)
+        var(--secondary-text-amount, var(--text-amount, 50%))
+    )
+  );
+  --info-text-fg: var(
+    --info-text-fg-override,
+    color-mix(
+      in srgb,
+      var(--_color),
+      var(--info-color)
+        var(--info-text-amount, var(--text-amount, 50%))
+    )
+  );
+  --success-text-fg: var(
+    --success-text-fg-override,
+    color-mix(
+      in srgb,
+      var(--_color),
+      var(--success-color)
+        var(--success-text-amount, var(--text-amount, 50%))
+    )
+  );
+  --warning-text-fg: var(
+    --warning-text-fg-override,
+    color-mix(
+      in srgb,
+      var(--_color),
+      var(--warning-color)
+        var(--warning-text-amount, var(--text-amount, 50%))
+    )
+  );
+  --danger-text-fg: var(
+    --danger-text-fg-override,
+    color-mix(
+      in srgb,
+      var(--_color),
+      var(--danger-color)
+        var(--danger-text-amount, var(--text-amount, 50%))
+    )
+  );
+  --muted-text-fg: var(
+    --muted-text-fg-override,
+    color-mix(
+      in srgb,
+      var(--_color),
+      var(--muted-color)
+        var(--muted-text-amount, var(--text-amount, 50%))
+    )
+  );
+  background-color: var(--_background-color);
+  color: var(--_color);
+  box-sizing: border-box;
+  --_padding: var(--sidebar-container-padding, var(--padding, 4px));
+  padding: var(--_padding);
+  border: var(--sidebar-container-border, var(--border, inherit));
+  border-width: var(--sidebar-container-border-width, var(--__missing-border-width));
+  border-style: var(--sidebar-container-border-style, var(--__missing-border-style));
+  border-color: var(--sidebar-container-border-color, var(--__missing-border-color));
+  border-top: var(--sidebar-container-border-top, var(--border-top, var(--sidebar-container-border, var(--border, none))));
+  border-right: var(--sidebar-container-border-right, var(--border-right, var(--sidebar-container-border, var(--border, none))));
+  border-bottom: var(--sidebar-container-border-bottom, var(--border-bottom, var(--sidebar-container-border, var(--border, none))));
+  border-left: var(--sidebar-container-border-left, var(--border-left, var(--sidebar-container-border, var(--border, none))));
+  border-radius: var(--sidebar-container-border-radius, var(--border-radius, none));
+  /* (1) so the Sidebar's container queries have something to measure */
+  container-type: inline-size;
+  /* (3) so the content sits beside the sidebar, not under it */
+  display: flex;
+  gap: var(--sidebar-container-gap, 0);
+  /* so an overlay sheet anchors here rather than escaping up the tree */
+  position: relative;
+  box-sizing: border-box;
+  width: var(--sidebar-container-width, 100%);
+  /* (2) a height to fill. `auto` would collapse, because a collapsed
+     sidebar has no in-flow content of its own. */
+  height: var(--sidebar-container-height, 100%);
+  min-height: var(--sidebar-container-min-height, 0);
+  /* Deliberately NOT `overflow: hidden`: that is what makes an overlay
+     sheet vanish inside a <Container>. */
+}
+
+.sidebar-container.right {
+  flex-direction: row-reverse;
+}
+
+/* The content beside the sidebar takes the remaining width and scrolls on
+   its own, so a long page does not stretch the sidebar past the viewport. */
+.sidebar-container > :global(:not(aside)) {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: auto;
+}</style>

package/dist/layout/SidebarContainer.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+import type { ContainProps } from "../types";
+import { type StyleProps } from "../styleProps";
+declare const SidebarContainer: import("svelte").Component<ContainProps<HTMLAttributes<HTMLDivElement>, {
+    /** Put the sidebar after the content in the flex row. Pair with
+     *  `<Sidebar right />`, which is what draws its border and rail on the
+     *  correct edge. */
+    right?: boolean;
+    children?: Snippet;
+}, StyleProps<readonly ["bg", "fg", "padding", "borderRadius"]> & {
+    /** Shorthands for --sidebar-container-{width,height,gap}. Height
+     *  matters: a collapsed sidebar has no in-flow content, so an auto
+     *  height collapses to nothing. */
+    width?: string | null;
+    height?: string | null;
+    gap?: string | null;
+}>, {}, "">;
+type SidebarContainer = ReturnType<typeof SidebarContainer>;
+export default SidebarContainer;

package/dist/layout/SplitPane.svelte

@@ -116,7 +116,33 @@ onMount(() => {
   </div>
 </div>
 
-<style>/* Logical, not top/bottom/left/right: margin-block/margin-inline already take
+<style>/* Per-level heading (h1-h6) box/typography properties, resolved to PRIVATE,
+   inheriting custom properties (--_h1-color, --_h2-font-size, etc) rather than
+   assigned directly to a matched h1-h6 selector. Nothing in this file matches
+   an actual heading element anymore -- see typography-context.css (vars/), which
+   is the single, global, :where()-scoped rule that actually reads these vars
+   and applies them to real elements. That split is what lets a component
+   nested arbitrarily deep (through <article>, <Tile>, whatever) still get the
+   nearest ancestor's heading styling: these are ordinary inherited custom
+   properties, so DOM proximity decides which component's values apply, not
+   selector specificity or stylesheet order. See AGENTS-INTERNAL.md. */
+/* All six heading levels' context vars in one call -- what every
+   "typography container" component (Container, Card, Tile, TextLayout, ...)
+   includes on itself once, alongside the shared --_heading-* vars below. */
+/* Shared prose-measure group: p, blockquote, dl, ul, ol. li/dt/dd don't get
+   their own vars -- they're never wider than their ul/ol/dl parent's own
+   max-width box, so they're already bounded for free by ordinary block
+   layout, not by anything selector-based reaching them individually. */
+/* p specifically also gets the fuller typography-props-bare treatment
+   (paragraph-prefixed), which -- same as in the original selector-based
+   version -- is declared/consumed AFTER the shared prose vars above, so it
+   wins for whichever properties both groups set. */
+/* The first paragraph in a typography context (p:first-of-type, or a p right
+   after a heading) gets its own, slightly different treatment -- larger lede
+   text, no top margin. Structural matching (:first-of-type, `h1 + p`) still
+   has to happen where the real element is, in the global consumer rule; only
+   the VALUES move to context vars here. */
+/* Logical, not top/bottom/left/right: margin-block/margin-inline already take
    one value (both sides equal) or two (start end), so there is no separate
    "which side" prop to remember and no 4-value shorthand order to get wrong.
    Defaults to 0 on purpose -- unlike padding-props above, a margin that
@@ -124,6 +150,18 @@ onMount(() => {
    day this mixin got added to a new component. Callers opt in with an actual
    value. (Container does not use this mixin: it wants --gap/auto as its
    defaults, which do not fit the "0 unless asked" contract here.) */
+/* The width at or below which a Sidebar swaps its grab-bar rail for the sheet
+   affordance -- a floating button that opens a panel over the content.
+
+   Page has to agree with Sidebar about this, because Page is what floats the
+   aside out of flow and reserves the strip of padding the sheet button sits
+   in. They used to disagree: Sidebar switched at 512px and Page at 600px,
+   which left a band between 513 and 600 where Page had already lifted the
+   aside out of the layout while the Sidebar inside it was still showing a
+   rail -- a grab bar floating on top of the content, which is the affordance
+   we deliberately avoid everywhere else.
+
+   One definition, used by both, so they cannot drift again. */
 /* Warning: because we define a fallback
   media query, the media query can override the container
   if we stack a bunch of these in a row and aren't thoughtful about the order.

package/dist/layout/Stack.svelte

@@ -32,7 +32,33 @@ const el = $derived(elementProps({ justify, align: resolvedAlign, gap, ...restPr
   {@render children?.()}
 </div>
 
-<style>/* Logical, not top/bottom/left/right: margin-block/margin-inline already take
+<style>/* Per-level heading (h1-h6) box/typography properties, resolved to PRIVATE,
+   inheriting custom properties (--_h1-color, --_h2-font-size, etc) rather than
+   assigned directly to a matched h1-h6 selector. Nothing in this file matches
+   an actual heading element anymore -- see typography-context.css (vars/), which
+   is the single, global, :where()-scoped rule that actually reads these vars
+   and applies them to real elements. That split is what lets a component
+   nested arbitrarily deep (through <article>, <Tile>, whatever) still get the
+   nearest ancestor's heading styling: these are ordinary inherited custom
+   properties, so DOM proximity decides which component's values apply, not
+   selector specificity or stylesheet order. See AGENTS-INTERNAL.md. */
+/* All six heading levels' context vars in one call -- what every
+   "typography container" component (Container, Card, Tile, TextLayout, ...)
+   includes on itself once, alongside the shared --_heading-* vars below. */
+/* Shared prose-measure group: p, blockquote, dl, ul, ol. li/dt/dd don't get
+   their own vars -- they're never wider than their ul/ol/dl parent's own
+   max-width box, so they're already bounded for free by ordinary block
+   layout, not by anything selector-based reaching them individually. */
+/* p specifically also gets the fuller typography-props-bare treatment
+   (paragraph-prefixed), which -- same as in the original selector-based
+   version -- is declared/consumed AFTER the shared prose vars above, so it
+   wins for whichever properties both groups set. */
+/* The first paragraph in a typography context (p:first-of-type, or a p right
+   after a heading) gets its own, slightly different treatment -- larger lede
+   text, no top margin. Structural matching (:first-of-type, `h1 + p`) still
+   has to happen where the real element is, in the global consumer rule; only
+   the VALUES move to context vars here. */
+/* Logical, not top/bottom/left/right: margin-block/margin-inline already take
    one value (both sides equal) or two (start end), so there is no separate
    "which side" prop to remember and no 4-value shorthand order to get wrong.
    Defaults to 0 on purpose -- unlike padding-props above, a margin that
@@ -40,6 +66,18 @@ const el = $derived(elementProps({ justify, align: resolvedAlign, gap, ...restPr
    day this mixin got added to a new component. Callers opt in with an actual
    value. (Container does not use this mixin: it wants --gap/auto as its
    defaults, which do not fit the "0 unless asked" contract here.) */
+/* The width at or below which a Sidebar swaps its grab-bar rail for the sheet
+   affordance -- a floating button that opens a panel over the content.
+
+   Page has to agree with Sidebar about this, because Page is what floats the
+   aside out of flow and reserves the strip of padding the sheet button sits
+   in. They used to disagree: Sidebar switched at 512px and Page at 600px,
+   which left a band between 513 and 600 where Page had already lifted the
+   aside out of the layout while the Sidebar inside it was still showing a
+   rail -- a grab bar floating on top of the content, which is the affordance
+   we deliberately avoid everywhere else.
+
+   One definition, used by both, so they cannot drift again. */
 /* Warning: because we define a fallback
   media query, the media query can override the container
   if we stack a bunch of these in a row and aren't thoughtful about the order.
@@ -60,6 +98,12 @@ const el = $derived(elementProps({ justify, align: resolvedAlign, gap, ...restPr
   border-bottom: var(--stack-border-bottom, var(--border-bottom, var(--stack-border, var(--border, none))));
   border-left: var(--stack-border-left, var(--border-left, var(--stack-border, var(--border, none))));
   border-radius: var(--stack-border-radius, var(--border-radius, none));
+  /* A layout helper, not a surface: padding comes only from
+     --stack-padding (or the `padding` prop), never from the theme's
+     --padding. box-props falls back to --padding, which is inherited, so
+     without this every Stack picked up the page's padding -- or
+     whatever padding an enclosing Card set. */
+  --_padding: var(--stack-padding, 0);
   --_margin-block: var(--stack-margin-block, var(--margin-block, 0));
   --_margin-inline: var(--stack-margin-inline, var(--margin-inline, 0));
   margin-block: var(--_margin-block);

package/dist/layout/TabBar.svelte

@@ -46,7 +46,33 @@ let lastActive = $state(active);
   </Bar>
 </div>
 
-<style>/* Logical, not top/bottom/left/right: margin-block/margin-inline already take
+<style>/* Per-level heading (h1-h6) box/typography properties, resolved to PRIVATE,
+   inheriting custom properties (--_h1-color, --_h2-font-size, etc) rather than
+   assigned directly to a matched h1-h6 selector. Nothing in this file matches
+   an actual heading element anymore -- see typography-context.css (vars/), which
+   is the single, global, :where()-scoped rule that actually reads these vars
+   and applies them to real elements. That split is what lets a component
+   nested arbitrarily deep (through <article>, <Tile>, whatever) still get the
+   nearest ancestor's heading styling: these are ordinary inherited custom
+   properties, so DOM proximity decides which component's values apply, not
+   selector specificity or stylesheet order. See AGENTS-INTERNAL.md. */
+/* All six heading levels' context vars in one call -- what every
+   "typography container" component (Container, Card, Tile, TextLayout, ...)
+   includes on itself once, alongside the shared --_heading-* vars below. */
+/* Shared prose-measure group: p, blockquote, dl, ul, ol. li/dt/dd don't get
+   their own vars -- they're never wider than their ul/ol/dl parent's own
+   max-width box, so they're already bounded for free by ordinary block
+   layout, not by anything selector-based reaching them individually. */
+/* p specifically also gets the fuller typography-props-bare treatment
+   (paragraph-prefixed), which -- same as in the original selector-based
+   version -- is declared/consumed AFTER the shared prose vars above, so it
+   wins for whichever properties both groups set. */
+/* The first paragraph in a typography context (p:first-of-type, or a p right
+   after a heading) gets its own, slightly different treatment -- larger lede
+   text, no top margin. Structural matching (:first-of-type, `h1 + p`) still
+   has to happen where the real element is, in the global consumer rule; only
+   the VALUES move to context vars here. */
+/* Logical, not top/bottom/left/right: margin-block/margin-inline already take
    one value (both sides equal) or two (start end), so there is no separate
    "which side" prop to remember and no 4-value shorthand order to get wrong.
    Defaults to 0 on purpose -- unlike padding-props above, a margin that
@@ -54,6 +80,18 @@ let lastActive = $state(active);
    day this mixin got added to a new component. Callers opt in with an actual
    value. (Container does not use this mixin: it wants --gap/auto as its
    defaults, which do not fit the "0 unless asked" contract here.) */
+/* The width at or below which a Sidebar swaps its grab-bar rail for the sheet
+   affordance -- a floating button that opens a panel over the content.
+
+   Page has to agree with Sidebar about this, because Page is what floats the
+   aside out of flow and reserves the strip of padding the sheet button sits
+   in. They used to disagree: Sidebar switched at 512px and Page at 600px,
+   which left a band between 513 and 600 where Page had already lifted the
+   aside out of the layout while the Sidebar inside it was still showing a
+   rail -- a grab bar floating on top of the content, which is the affordance
+   we deliberately avoid everywhere else.
+
+   One definition, used by both, so they cannot drift again. */
 /* Warning: because we define a fallback
   media query, the media query can override the container
   if we stack a bunch of these in a row and aren't thoughtful about the order.