contain-css-svelte 1.1.9 → 1.1.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tom Hinkle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,58 +1,138 @@
-# create-svelte
+# ContainCSS for Svelte
 
-Everything you need to build a Svelte library, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/master/packages/create-svelte).
+**A small Svelte component library that gets out of your way.** Every component is
+styled through CSS custom properties, sized by container queries, and built on
+native HTML elements — so you can theme it from the outside, drop it into any
+layout, and keep the accessibility you get for free from `<dialog>`, `<details>`,
+and `popover`.
 
-Read more about creating a library [in the docs](https://kit.svelte.dev/docs/packaging).
+### 📖 [Browse the docs & live demos →](https://thinkle.github.io/svelte-contain-css/)
 
-## Creating a project
+[![npm](https://img.shields.io/npm/v/contain-css-svelte.svg)](https://www.npmjs.com/package/contain-css-svelte)
 
-If you're seeing this, you've probably already done this step. Congrats!
+---
 
-```bash
-# create a new project in the current directory
-npm create svelte@latest
+## Which version do I want?
 
-# create a new project in my-app
-npm create svelte@latest my-app
-```
+| | Branch | npm version | Svelte | Docs |
+| --- | --- | --- | --- | --- |
+| **👉 Start here** | [`svelte5`](https://github.com/thinkle/svelte-contain-css/tree/svelte5) | `1.x` | Svelte 5 | [svelte5 docs](https://thinkle.github.io/svelte-contain-css/svelte5/) |
+| Legacy | [`main`](https://github.com/thinkle/svelte-contain-css/tree/main) | `0.0.x` | Svelte 3 & 4 | [legacy docs](https://thinkle.github.io/svelte-contain-css/legacy/) |
 
-## Developing
+**`svelte5` is the active development branch** and where all new work lands.
+`main` is frozen for existing Svelte 4 and earlier projects; it gets fixes
+backported when they're worth it, but no new features. If you're starting
+something new, use `svelte5` / `1.x`.
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+## Install
 
 ```bash
-npm run dev
+npm install contain-css-svelte
+```
 
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
+Import the default variables once, at the root of your app:
+
+```svelte
+<!-- +layout.svelte or App.svelte -->
+<script>
+  import "contain-css-svelte/vars/defaults.css";
+</script>
 ```
 
-Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
+Then use components anywhere:
+
+```svelte
+<script>
+  import { Container, Button, Card } from "contain-css-svelte";
+</script>
 
-## Building
+<Container>
+  <Card>
+    <h2>Hello</h2>
+    <Button primary>Do the thing</Button>
+  </Card>
+</Container>
+```
 
-To build your library:
+## The idea
 
-```bash
-npm run package
+**1. Style props are CSS variables, not inline styles.**
+
+```svelte
+<Button bg="green" fg="white" height="64px">Wow</Button>
+<!-- becomes style="--button-bg: green; --button-fg: white; --button-height: 64px" -->
 ```
 
-To create a production version of your showcase app:
+Because they're variables rather than hard-coded styles, the cascade still
+works — which means you can theme a whole subtree from above:
 
-```bash
-npm run build
+```svelte
+<div style="--primary-bg: darkblue; --primary-fg: white; --border-radius: 0">
+  <Button primary>Themed</Button>
+  <Button primary>Also themed</Button>
+</div>
+```
+
+...or in plain CSS, with no build step and no wrapper components:
+
+```css
+.my-app {
+  --bg: #1a1a1a;
+  --fg: #fff;
+  --primary-bg: #4a90d9;
+  --font-family: "Inter", sans-serif;
+}
 ```
 
-You can preview the production build with `npm run preview`.
+**2. Components respond to their container, not the viewport.** A `Card` in a
+narrow sidebar lays itself out like a narrow card, whether or not the window is
+wide. No breakpoint bookkeeping.
+
+**3. Native elements underneath.** `Dialog` is a real `<dialog>`, `Accordion` is
+`<details>`, `Tooltip` uses the `popover` API. Focus trapping, escape-to-close,
+and screen-reader semantics come from the platform.
+
+## What's in the box
+
+- **Controls** — `Button`, `ButtonLink`, `MiniButton`, `Input`, `Select`,
+  `Checkbox`, `RadioButton`, `Toggle`, `Slider`
+- **Layout** — `Container`, `Page`, `Row`/`Column`/`Columns`, `Stack`, `Inline`,
+  `GridLayout`, `SplitPane`, `Sidebar`, `Bar`, `TabBar`, `Table`, `Tile`,
+  `DataList`, `Hero`, `Accordion`, `Form`/`FormItem`/`Fieldset`
+- **Overlays** — `Dialog`, `Tooltip`, `DropdownMenu`
+- **Misc** — `Card`, `Code`, `Progress`, `Tag`, `TextLayout`, `ResponsiveText`
 
-> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment.
+Plus a set of ready-made themes (`light`, `dark`, `material`, `bootstrap`,
+`retro`, `purple`, `forest`, `canyon`, and several typography-only themes) under
+`contain-css-svelte/themes/`.
 
-## Publishing
+Every component and every CSS variable is documented with a live, editable demo
+in [the docs site](https://thinkle.github.io/svelte-contain-css/svelte5/).
 
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
+## Using this with an AI assistant
 
-To publish your library to [npm](https://www.npmjs.com):
+[`AGENTS-EXTERNAL.md`](AGENTS-EXTERNAL.md) is a complete reference written for
+coding agents — component list, prop-to-variable conventions, and the full CSS
+variable table. Point your assistant at it (or drop it in your project) and it
+will write idiomatic ContainCSS code.
+
+## Developing the library
 
 ```bash
-npm publish
+npm install
+npm run dev        # docs site + live demos at localhost:5173
+npm run check      # svelte-check
+npm run test:e2e   # playwright
+npm run package    # build dist/
 ```
+
+The docs site lives in `src/routes`; the library itself is `src/lib`. Pushing to
+`svelte5` or `main` rebuilds and publishes both doc versions to GitHub Pages via
+[`.github/workflows/deploy-docs.yml`](.github/workflows/deploy-docs.yml).
+
+See [AGENTS-INTERNAL.md](AGENTS-INTERNAL.md) for library-development conventions
+and [BACKPORT.md](BACKPORT.md) for moving fixes to the legacy branch.
+
+## License
+
+MIT © [Tom Hinkle](https://tomhinkle.net)

package/dist/controls/Option.svelte

@@ -1,8 +1,36 @@
 <script lang="ts">let { children, value, ...restProps } = $props();
 let template = $state();
-// Extract text content from rendered children
-let textContent = $derived(template ? template.textContent ?? "" : "");
-let htmlContent = $derived(template ? template.innerHTML : "");
+// Extracted from the rendered children, in the DOM.
+let textContent = $state("");
+let htmlContent = $state("");
+function syncFromTemplate() {
+    if (!template)
+        return;
+    textContent = template.textContent ?? "";
+    htmlContent = template.innerHTML;
+}
+/*
+  These have to be read back out of the DOM, and a $derived would only
+  recompute when `template` itself changed -- which it never does once the
+  element is bound. So rendering different content into the snippet (renaming
+  a label, say) left the <option> showing whatever it was first given.
+
+  Watching the template covers that: any change to the rendered children
+  re-extracts the html and text.
+*/
+$effect(() => {
+    if (!template)
+        return;
+    syncFromTemplate();
+    const observer = new MutationObserver(syncFromTemplate);
+    observer.observe(template, {
+        childList: true,
+        subtree: true,
+        characterData: true,
+        attributes: true,
+    });
+    return () => observer.disconnect();
+});
 export {};
 </script>
 

package/dist/controls/Select.svelte

@@ -8,16 +8,25 @@ let targetWidth = $state("");
 let optionButtons = $state([]);
 onMount(() => {
     tick().then(() => updateOptions());
-    // Observe changes in the select element
-    observer = new MutationObserver((mutations) => {
-        mutations.forEach((mutation) => {
-            if (mutation.type === "childList") {
-                updateOptions();
-            }
-        });
-    });
+    /*
+      Watch the options for any change, not just being added or removed. An
+      <Option> whose content is rewritten in place -- a label being renamed --
+      updates its own data-html without touching the child list, and a
+      childList-only observer never hears about it, so the dropdown kept
+      rendering the snapshot it took on mount.
+
+      Coalesced into one pass per microtask: a single re-render can produce a
+      burst of mutations, and updateOptions() measures layout.
+    */
+    observer = new MutationObserver(() => scheduleUpdateOptions());
     if (selectElement) {
-        observer.observe(selectElement, { childList: true });
+        observer.observe(selectElement, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+            attributes: true,
+            attributeFilter: ["data-html", "value", "label", "selected"],
+        });
     }
     // Observe size changes in option buttons
     resizeObserver = new ResizeObserver(() => updateTargetWidth());
@@ -29,6 +38,16 @@ onMount(() => {
 });
 let options = $state([]);
 let activeOption = $state(null);
+let updateQueued = false;
+function scheduleUpdateOptions() {
+    if (updateQueued)
+        return;
+    updateQueued = true;
+    queueMicrotask(() => {
+        updateQueued = false;
+        updateOptions();
+    });
+}
 function updateOptions() {
     if (!selectElement) {
         return;

package/dist/controls/TabItem.svelte

@@ -73,8 +73,7 @@ const style = $derived(injectVars(restProps, "tab", ["bg", "fg", "padding", "wid
 .tab > :global(button):focus-visible,
 .tab > :global(div > button):focus-visible {
   outline: var(--focus-color, -webkit-focus-ring-color) auto 1px;
-  outline-offset: var(--focus-outline-offset, 2px);
-  box-shadow: var(--focus-ring-box-shadow, 0 0 0 3px var(--focus-shadow-color, rgba(100, 150, 250, 0.5)));
+  outline-offset: var(--focus-inset-outline-offset, -3px);
 }
 
 .tab > :global(button),

package/dist/cssprops.js

@@ -126,6 +126,7 @@ const components = [
     ...[
         "button",
         "mini-button",
+        "menu",
         "menu-trigger",
         "menu-item",
         "dropdown-menu",

package/dist/dropdowns/DropdownMenu.svelte

@@ -56,28 +56,41 @@ function dismissPopover(_e) {
 }
 function handleToggle(event) {
     isOpen = event.newState === "open";
+    if (!isOpen)
+        clearSearch();
+}
+let searchString = $state("");
+let clearTimer;
+function clearSearch() {
+    clearTimeout(clearTimer);
+    clearTimer = undefined;
+    searchString = "";
+}
+const timeoutAfterMS = 2500; // 2.5 seconds seems more humane
+function scheduleSearchClear() {
+    clearTimeout(clearTimer);
+    clearTimer = setTimeout(clearSearch, timeoutAfterMS);
 }
-let searchString = "";
-let lastPress;
 function handleKeystroke(event) {
     if (event.key == "Backspace" && searchString) {
         searchString = searchString.slice(0, -1);
+        scheduleSearchClear();
     }
     else if (event.key.length == 1) {
         if (searchString || event.key != " ") {
             searchString += event.key;
             maybeFocusMatch(searchString);
+            scheduleSearchClear();
         }
     }
     else {
-        searchString = "";
+        clearSearch();
         if (event.key === "Escape") {
             popoverDiv?.hidePopover();
         }
         else if (event.key === "ArrowDown" || event.key === "ArrowUp") {
             event.preventDefault(); // Prevent default to stop scrolling the page
             navigateMenu(event.key);
-            searchString = "";
         }
     }
 }
@@ -158,6 +171,9 @@ let popoverDiv = $state();
     style:left="{dropdownLeft}px"
     style:max-height="{dropdownMaxHeight}px"
   >
+    {#if searchString}
+      <div class="search-hint" aria-hidden="true">{searchString}</div>
+    {/if}
     <!-- svelte-ignore a11y_no_static_element_interactions -->
     <div
       class="dropdown-content"
@@ -418,6 +434,65 @@ button {
   overflow: hidden;
 }
 
+.search-hint {
+  position: absolute;
+  top: var(--search-hint-offset, 4px);
+  right: var(--search-hint-offset, 4px);
+  z-index: 2;
+  pointer-events: none;
+  max-width: calc(100% - 2 * var(--search-hint-offset, 4px));
+  --link-bg: var(--search-hint-link-bg, var(--tag-link-bg, var(--secondary-link-bg, inherit)));
+  --link-fg: var(--search-hint-link-fg, var(--tag-link-fg, var(--secondary-link-fg, inherit)));
+  --_bg-mix-color: var(--search-hint-bg-mix-color, var(--tag-bg-mix-color, var(--secondary-bg-mix-color, var(--bg-mix-color, transparent))));
+  --_bg-mix-amount: var(--search-hint-bg-mix-amount, var(--tag-bg-mix-amount, var(--secondary-bg-mix-amount, var(--bg-mix-amount, 0%))));
+  --_fg-mix-color: var(--search-hint-fg-mix-color, var(--tag-fg-mix-color, var(--secondary-fg-mix-color, var(--fg-mix-color, transparent))));
+  --_fg-mix-amount: var(--search-hint-fg-mix-amount, var(--tag-fg-mix-amount, var(--secondary-fg-mix-amount, var(--fg-mix-amount, 0%))));
+  --_bg-base: var(--search-hint-bg, var(--tag-bg, var(--secondary-bg, var(--bg, unset))));
+  --_fg-base: var(--search-hint-fg, var(--tag-fg, var(--secondary-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));
+  background-color: var(--_background-color);
+  color: var(--_color);
+  font-family: var(--search-hint-font-family, var(--tag-font-family, inherit));
+  text-transform: var(--search-hint-text-transform, var(--tag-text-transform, inherit));
+  text-decoration: var(--search-hint-text-decoration, var(--tag-text-decoration, inherit));
+  --_font-size: var(--search-hint-font-size, var(--tag-font-size, inherit));
+  font-size: var(--_font-size);
+  font-weight: var(--search-hint-font-weight, var(--tag-font-weight, inherit));
+  line-height: var(--search-hint-line-height, var(--tag-line-height, inherit));
+  letter-spacing: var(--search-hint-letter-spacing, var(--tag-letter-spacing, inherit));
+  text-indent: var(--search-hint-indent, var(--tag-indent, inherit));
+  font-variant: var(--search-hint-font-variant, var(--tag-font-variant, inherit));
+  text-align: var(--search-hint-text-align, var(--tag-text-align, inherit));
+  box-sizing: border-box;
+  --_padding: var(--search-hint-padding, var(--tag-padding, var(--padding, 4px)));
+  padding: var(--_padding);
+  border: var(--search-hint-border, var(--tag-border, var(--border, inherit)));
+  border-width: var(--search-hint-border-width, var(--tag-border-width, var(--__missing-border-width)));
+  border-style: var(--search-hint-border-style, var(--tag-border-style, var(--__missing-border-style)));
+  border-color: var(--search-hint-border-color, var(--tag-border-color, var(--__missing-border-color)));
+  border-top: var(--search-hint-border-top, var(--tag-border-top, var(--border-top, var(--search-hint-border, var(--tag-border, var(--border, none))))));
+  border-right: var(--search-hint-border-right, var(--tag-border-right, var(--border-right, var(--search-hint-border, var(--tag-border, var(--border, none))))));
+  border-bottom: var(--search-hint-border-bottom, var(--tag-border-bottom, var(--border-bottom, var(--search-hint-border, var(--tag-border, var(--border, none))))));
+  border-left: var(--search-hint-border-left, var(--tag-border-left, var(--border-left, var(--search-hint-border, var(--tag-border, var(--border, none))))));
+  border-radius: var(--search-hint-border-radius, var(--tag-border-radius, var(--border-radius, none)));
+  font-size: var(--search-hint-font-size, var(--font-size-small, 0.75rem));
+  padding: var(--search-hint-padding, 0.2em 0.55em);
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  border-radius: var(--search-hint-radius, var(--border-radius, 4px));
+  --_box-shadow:
+    var(--search-hint-shadow-distance, var(--dropdown-shadow-distance, var(--shadow-distance, var(--space)))) var(--search-hint-shadow-distance, var(--dropdown-shadow-distance, var(--shadow-distance, var(--space)))) var(--search-hint-shadow-blur, var(--dropdown-shadow-blur, var(--shadow-blur, var(--space)))) var(--search-hint-shadow-color, var(--dropdown-shadow-color, var(--shadow-color, rgba(127, 127, 127, 0.4))));
+  box-shadow: var(--_box-shadow);
+  opacity: var(--search-hint-opacity, 0.95);
+}
+
 .dropdown-content :global(button),
 .dropdown-content :global(a) {
   white-space: var(--dropdown-wrap-mode, wrap);

package/dist/index.d.ts

@@ -23,6 +23,7 @@ import Form from "./layout/Form.svelte";
 import FormItem from "./layout/FormItem.svelte";
 import FormProvider from "./layout/FormProvider.svelte";
 import GridLayout from "./layout/GridLayout.svelte";
+import GridRow from "./layout/GridRow.svelte";
 import Hero from "./layout/Hero.svelte";
 import Inline from "./layout/Inline.svelte";
 import MenuList from "./layout/MenuList.svelte";
@@ -48,7 +49,7 @@ export { Tag };
 export { Hero };
 export { TabItem };
 export { Button, ButtonLink, Checkbox, Input, Slider, Toggle, RadioButton, MiniButton, Select, Option, };
-export { Bar, ColumnContainer, Container, GridLayout, Inline, MenuList, Page, ResponsiveText, RowContainer, Stack, TabBar, };
+export { Bar, ColumnContainer, Container, GridLayout, GridRow, Inline, MenuList, Page, ResponsiveText, RowContainer, Stack, TabBar, };
 export { TextLayout, Code, Accordion };
 export { Card, Tile, Form, FormItem, FormProvider, Fieldset };
 export { DataList, DataListItem };

package/dist/index.js

@@ -24,6 +24,7 @@ import Form from "./layout/Form.svelte";
 import FormItem from "./layout/FormItem.svelte";
 import FormProvider from "./layout/FormProvider.svelte";
 import GridLayout from "./layout/GridLayout.svelte";
+import GridRow from "./layout/GridRow.svelte";
 import Hero from "./layout/Hero.svelte";
 import Inline from "./layout/Inline.svelte";
 import MenuList from "./layout/MenuList.svelte";
@@ -48,7 +49,7 @@ export { Tag };
 export { Hero };
 export { TabItem };
 export { Button, ButtonLink, Checkbox, Input, Slider, Toggle, RadioButton, MiniButton, Select, Option, };
-export { Bar, ColumnContainer, Container, GridLayout, Inline, MenuList, Page, ResponsiveText, RowContainer, Stack, TabBar, };
+export { Bar, ColumnContainer, Container, GridLayout, GridRow, Inline, MenuList, Page, ResponsiveText, RowContainer, Stack, TabBar, };
 export { TextLayout, Code, Accordion };
 export { Card, Tile, Form, FormItem, FormProvider, Fieldset };
 export { DataList, DataListItem };

package/dist/layout/GridLayout.svelte

@@ -11,7 +11,8 @@ export {};
   {@render children?.()}
 </div>
 
-<style>/* Warning: because we define a fallback
+<style>@charset "UTF-8";
+/* 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
@@ -20,10 +21,58 @@ export {};
 /* Convenience groupings */
 .grid-layout {
   display: grid;
-  grid-template-columns: repeat(auto-fill, minmax(min(100%, var(--grid-layout-item-width, var(--item-width, 250px))), 1fr));
+  /* Tracks sized to the item, not `1fr`.
+
+     `1fr` splits the leftover width between the tracks, which turns it into
+     gutter *between* the items while the edges of the run stay tight -- three
+     cards in a 900px container end up sprung apart and pushed left. That is
+     rarely what anyone means by declaring an item width: they mean "lay these
+     out at this size", and the leftover belongs at the edges.
+
+     Sizing the track to the item gives exactly the `gap` that was asked for
+     between items, and hands the remainder to `justify-content: center` below,
+     which centres the whole run. That declaration has been here all along and
+     could never fire, because `1fr` tracks always consume the full width.
+
+     `min(100%, …)` keeps a track from outgrowing a narrow screen.
+
+     `auto-fit`, not `auto-fill`, and the difference is the whole ballgame for
+     centring. Both lay down as many tracks as fit the container; `auto-fill`
+     keeps the empty ones at full width, so three cards in a wide container
+     leave `justify-content` no slack to work with and pack against the left.
+     `auto-fit` collapses the tracks nothing landed in, so the run shrinks to
+     the items and centres. Three 200px items in a 1400px container: 72px left
+     and 696px right under `auto-fill`, 384px either side under `auto-fit`.
+
+     One caveat worth knowing, because it is not a bug we can fix here: an item
+     spanning `1 / -1` -- a `GridRow`, a heading -- occupies every track, so
+     there is nothing left for `auto-fit` to collapse and the run goes back to
+     full width and left-packed. A grid with full-width rows in it is a
+     full-width grid. Headings kept outside the grid, one grid per section,
+     keep the centring. */
+  grid-template-columns: repeat(auto-fit, min(100%, var(--grid-layout-item-width, var(--item-width, 250px))));
   gap: var(--grid-layout-gap, var(--gap, 8px));
-  justify-content: var(--grid-justify-content, center);
-  place-content: var(--grid-place-content, center);
+  /* Where the run of tracks sits in the grid box. Both axes as longhands,
+     because `place-content` is a shorthand and was declared after
+     `justify-content` here -- so it quietly overwrote it and
+     `--grid-justify-content` never did anything at all. Only
+     `--grid-place-content` worked, and it moves both axes at once.
+
+     Named `--grid-layout-*` like everything else, with the old spellings kept
+     as fallbacks so anything already setting them keeps working -- and
+     `--grid-justify-content` starts working for the first time. */
+  justify-content: var(--grid-layout-justify-content, var(--justify-content, var(--grid-justify-content, var(--grid-place-content, center))));
+  align-content: var(--grid-layout-align-content, var(--align-content, var(--grid-place-content, center)));
+  /* Where an item sits *inside* its track -- a separate question from where
+     the tracks sit in the grid, which is `justify-content` above.
+
+     Mostly moot now that a track is sized to the item: there is usually no
+     room inside a track to sit anywhere. It still matters when a child is
+     narrower than the track it was handed, which happens whenever a component
+     carries its own width -- a `Tile` with a `--tile-width` smaller than the
+     grid's `--item-width`. The default stays `stretch` so anything that can
+     use its whole track still gets it. */
+  justify-items: var(--grid-layout-justify-items, var(--justify-items, stretch));
   box-sizing: border-box;
   --_padding: var(--grid-layout-padding, var(--padding, 4px));
   padding: var(--_padding);
@@ -38,10 +87,56 @@ export {};
   border-radius: var(--grid-layout-border-radius, var(--border-radius, none));
 }
 
+/* Escape hatch for the things in a grid that are not items in the run: a
+   section heading, or a note explaining why the grid is empty. Both want the
+   whole row rather than one item-width column with tiles beside them.
+
+   Declared here so it travels with the component, and matched as a descendant
+   rather than a child on purpose -- a component handed a CSS custom property
+   is wrapped in a `<svelte-css-wrapper>`, so it is a grandchild of the grid
+   even though it is still the grid item. `grid-column` is inert on anything
+   that is not a grid item, so the looser match costs nothing. */
+.grid-layout :global(.grid-full-row) {
+  grid-column: 1/-1;
+  /* Spanning is only half of it. How an item fills the tracks it spans is
+     `justify-items` on the grid, which a tile grid sets to `center` -- and a
+     centred block with no width of its own shrinks to fit its content, so the
+     row it spans renders as a short centred blob rather than a full-width
+     heading. Saying `stretch` here makes the class mean the same thing in
+     every grid, whatever the container prefers for ordinary items.
+
+     A consumer spanning their own item -- `grid-column: span 2` -- owns this
+     decision themselves and will want `justify-self` alongside it. */
+  justify-self: var(--grid-row-justify, var(--justify, stretch));
+  /* And the typography has to be let go of too, which is the part that took a
+     while to see. A heading inside a typographic container gets a readable
+     measure and auto side margins -- `max-width: var(--line-width)`, 42rem by
+     default, with `margin-inline: auto` -- so it sits as a centred column of
+     text. Sensible for prose, wrong for a band that is supposed to run the
+     width of a grid.
+
+     Worse, an auto inline margin makes `justify-self: stretch` do nothing at
+     all: the spec only stretches a box whose inline margins are both
+     non-auto, so the heading fell back to shrink-to-fit. "Sections" measured
+     74px in a 1064px row, and computed style reports the *used* margin as
+     `0px`, so it does not look like margins are the culprit until you set them
+     and watch the width jump. */
+  max-width: none;
+  margin-inline: 0;
+}
+
 .card-grid {
   --item-width: var(--card-width, 400px);
 }
 
 .tile-grid {
-  --item-width: var(--tile-width, 200px);
+  /* Has to be the width a Tile actually defaults to, not a round number near
+     it. Tile says `calc(var(--space-lg) * 24)`, which is 192px; this said
+     200px, so every tile sat 4px inside its own track and a full-width row
+     did not line up with the tiles under it. */
+  --item-width: var(--tile-width, calc(var(--space-lg) * 24));
+  /* The track now matches `--item-width`, so this only bites when a Tile is
+     narrower than the track it was handed -- a `--tile-width` set smaller than
+     the grid's item width, say. */
+  --justify-items: center;
 }</style>

package/dist/layout/GridRow.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">import { injectVars } from "../util";
+let { justify = null, center = false, children, ...restProps } = $props();
+const resolvedJustify = $derived(justify ?? (center ? "center" : null));
+const inlineStyle = $derived(restProps.style);
+const elementProps = $derived.by(() => {
+    const { style: _, ...rest } = restProps;
+    return rest;
+});
+const style = $derived(injectVars({ justify: resolvedJustify, ...elementProps }, "grid-row", ["justify"]) +
+    (inlineStyle ?? ""));
+</script>
+
+<div class="grid-full-row grid-row" {...elementProps} {style}>
+  {@render children?.()}
+</div>
+
+<style>.grid-row {
+  /* Spanning, stretching and the margin reset all live on `.grid-full-row`,
+     in GridLayout. What this adds is releasing the measure for the content:
+     without it a heading in here is clamped to `--line-width` and centred by
+     its own auto margins, so the band spans and the words inside it do not. */
+  --line-width: none;
+}</style>

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

@@ -0,0 +1,24 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+/**
+ * A full-width band inside a GridLayout: a section heading, an explanation, a
+ * note saying why the grid is empty. Anything that belongs *in* the run of
+ * items without being one of them.
+ *
+ * Carries `.grid-full-row`, which is the same thing as a class for when you
+ * already have an element and would rather not nest a div inside it. The
+ * difference is `--line-width`: a heading or paragraph placed inside this
+ * component is meant to run the width of the band, so the readable measure
+ * that typographic containers impose is lifted for its contents too. Put the
+ * class on your own heading instead and the heading keeps that measure.
+ */
+type Props = {
+    /** How the row sits in the span it covers: start, center, end, stretch. */
+    justify?: string | null;
+    /** Shorthand for `justify="center"`, as `Stack` takes `center`. */
+    center?: boolean;
+    children?: Snippet;
+} & HTMLAttributes<HTMLDivElement>;
+declare const GridRow: import("svelte").Component<Props, {}, "">;
+type GridRow = ReturnType<typeof GridRow>;
+export default GridRow;

package/dist/layout/MenuList.svelte

@@ -139,9 +139,12 @@ const style = $derived(injectVars(restProps, "menu", [
 .menu :global(li.interactive):focus-visible,
 .menu :global(li[role="button"]):focus-visible,
 .menu :global(li[tabindex]:not([tabindex="-1"])):focus-visible {
+  filter: var(--menu-item-hover-filter, var(--hover-filter, brightness(1.05)));
+  transform: var(--menu-item-hover-transform, var(--hover-transform, none));
+  background-color: color-mix(in oklch, var(--_background-color) var(--hover-base-color-percentage, 90%), var(--hover-color-mix, white) calc(100% - var(--hover-base-color-percentage, 90%)));
+  box-shadow: var(--menu-item-hover-box-shadow, var(--hover-box-shadow, var(--_box-shadow, none)));
   outline: var(--focus-color, -webkit-focus-ring-color) auto 1px;
-  outline-offset: var(--focus-outline-offset, 2px);
-  box-shadow: var(--focus-ring-box-shadow, 0 0 0 3px var(--focus-shadow-color, rgba(100, 150, 250, 0.5)));
+  outline-offset: var(--focus-inset-outline-offset, -3px);
 }
 
 .menu :global(li > .subheader) {
@@ -205,9 +208,12 @@ const style = $derived(injectVars(restProps, "menu", [
 }
 
 .menu :global(a):focus-visible, .menu :global(button):focus-visible, .menu :global(input[type="submit"]):focus-visible, .menu :global(.button):focus-visible {
+  filter: var(--menu-item-hover-filter, var(--hover-filter, brightness(1.05)));
+  transform: var(--menu-item-hover-transform, var(--hover-transform, none));
+  background-color: color-mix(in oklch, var(--_background-color) var(--hover-base-color-percentage, 90%), var(--hover-color-mix, white) calc(100% - var(--hover-base-color-percentage, 90%)));
+  box-shadow: var(--menu-item-hover-box-shadow, var(--hover-box-shadow, var(--_box-shadow, none)));
   outline: var(--focus-color, -webkit-focus-ring-color) auto 1px;
-  outline-offset: var(--focus-outline-offset, 2px);
-  box-shadow: var(--focus-ring-box-shadow, 0 0 0 3px var(--focus-shadow-color, rgba(100, 150, 250, 0.5)));
+  outline-offset: var(--focus-inset-outline-offset, -3px);
 }
 
 .menu :global(a), .menu :global(button), .menu :global(input[type="submit"]), .menu :global(.button) {

package/dist/layout/Table.svelte

@@ -1,5 +1,4 @@
-<script lang="ts">import { run } from "svelte/legacy";
-let { sticky = false, column_widths = null, thead, tbody, children, } = $props();
+<script lang="ts">let { sticky = false, column_widths = null, thead, tbody, children, } = $props();
 // svelte-ignore state_referenced_locally
 let columns = $state(column_widths || []);
 /* Code for syncing column widths for scrolling table solution */
@@ -205,6 +204,10 @@ function setupWidths() {
   container queries don't get their styles overridden by large media queries.
   */
 /* Convenience groupings */
+table:has(colgroup) {
+  table-layout: fixed;
+}
+
 table {
   --link-bg: var(--table-link-bg, var(--surface-link-bg, inherit));
   --link-fg: var(--table-link-fg, var(--surface-link-fg, inherit));
@@ -621,7 +624,7 @@ table :global(tr > th:first-child:has(~ td)) {
   position: sticky;
   top: 0;
   z-index: 1;
-  background: var(--white);
+  background: var(--_background-color, var(--white, #fff));
   margin-inline-start: auto;
   margin-inline-end: auto;
 }
@@ -637,7 +640,7 @@ table :global(tr > th:first-child:has(~ td)) {
 }
 
 .veil {
-  background-color: var(--white, #fff);
+  background-color: var(--_background-color, var(--white, #fff));
   position: sticky;
   top: -2em;
   height: 3em;
@@ -808,4 +811,17 @@ table :global(td[tabindex]):focus-visible {
   outline: var(--focus-color, -webkit-focus-ring-color) auto 1px;
   outline-offset: var(--focus-outline-offset, 2px);
   box-shadow: var(--focus-ring-box-shadow, 0 0 0 3px var(--focus-shadow-color, rgba(100, 150, 250, 0.5)));
+}
+
+/* Apply thick border to column 1 in BOTH header and body tables, 
+ BUT ONLY IF the scrolling table contains row headers in its tbody */
+.scrolling-table:has(.scrolling-table-body :global(tbody > tr > th:first-child)) .fixed-table-head :global(tr > th:first-child),
+.scrolling-table:has(.scrolling-table-body :global(tbody > tr > th:first-child)) .scrolling-table-body :global(tbody > tr > th:first-child) {
+  border-right: var(--table-first-row-bottom-border, var(--table-thick-border, 3px) solid var(--table-first-row-border-color, var(--secondary-bg))) !important;
+}
+
+/* 2. Standard non-scrolling single <table> setup */
+table:has(:global(tbody > tr > th:first-child)) :global(thead > tr > th:first-child),
+table:has(:global(tbody > tr > th:first-child)) :global(tbody > tr > th:first-child) {
+  border-right: var(--table-first-row-bottom-border, var(--table-thick-border, 3px) solid var(--table-first-row-border-color, var(--secondary-bg)));
 }</style>

package/dist/layout/Tile.svelte

@@ -1,28 +1,54 @@
-<script lang="ts">let { checked = $bindable(false), ...props } = $props();
+<script lang="ts">import { injectVars } from "../util";
+let { checked = $bindable(false), ...props } = $props();
+/* Props to CSS variables, the way Stack, Card, Tag and the rest do it, so a
+   Tile can be aimed with `<Tile center>` rather than only a raw variable. */
+const styleProps = $derived.by(() => {
+    const { justify = null, align = null, center = false, bg = null, fg = null, padding = null, width = null, height = null, } = props;
+    return {
+        bg,
+        fg,
+        padding,
+        width,
+        height,
+        justify: justify ?? (center ? "center" : null),
+        align: align ?? (center ? "center" : null),
+    };
+});
+const style = $derived(injectVars(styleProps, "tile", [
+    "bg",
+    "fg",
+    "padding",
+    "width",
+    "height",
+    "justify",
+    "align",
+]) + (props.style ?? ""));
+/** Everything that is ours rather than the element's. */
+function stripOwnProps(value) {
+    const { selectable: _selectable, interactive: _interactive, children: _children, justify: _justify, align: _align, center: _center, bg: _bg, fg: _fg, padding: _padding, width: _width, height: _height, style: _style, ...rest } = value;
+    return rest;
+}
 function getSelectableInputProps(value) {
-    const { selectable: _selectable, interactive: _interactive, children: _children, ...inputProps } = value;
-    return inputProps;
+    return stripOwnProps(value);
 }
 function getInteractiveButtonProps(value) {
-    const { selectable: _selectable, interactive: _interactive, children: _children, ...buttonProps } = value;
-    return buttonProps;
+    return stripOwnProps(value);
 }
-export {};
 </script>
 
 {#if props.selectable}
-  <label class="tile">
+  <label class="tile" {style}>
     <div class="checkbox">
       <input type="checkbox" bind:checked {...getSelectableInputProps(props)} />
     </div>
     {@render props.children?.()}
   </label>
 {:else if props.interactive}
-  <button class="tile" {...getInteractiveButtonProps(props)}>
+  <button class="tile" {style} {...getInteractiveButtonProps(props)}>
     {@render props.children?.()}
   </button>
 {:else}
-  <div class="tile">
+  <div class="tile" {style} {...stripOwnProps(props as RenderProps)}>
     {@render props.children?.()}
   </div>
 {/if}

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

@@ -1,6 +1,18 @@
 import type { Snippet } from "svelte";
 import type { HTMLAttributes, HTMLButtonAttributes, HTMLInputAttributes } from "svelte/elements";
-type BaseProps = {
+import type { BaseStyleProps } from "../types";
+type BaseProps = BaseStyleProps & {
+    /** Distribution along the tile's own axis, which is vertical. */
+    justify?: string | null;
+    /** Cross-axis alignment, which is horizontal. Centred already. */
+    align?: string | null;
+    /**
+     * Shorthand for centring the tile's contents. Sets both axes, unlike
+     * `Stack`'s `center`, because a Tile already centres horizontally -- setting
+     * only the cross axis here would be a no-op and `<Tile center>` would look
+     * broken.
+     */
+    center?: boolean;
     children?: Snippet;
 };
 type StaticTileProps = BaseProps & HTMLAttributes<HTMLDivElement> & {

package/dist/review/ReviewAppPage.svelte

@@ -1,4 +1,5 @@
-<script lang="ts">import ReviewThemeSwitcher from "./ReviewThemeSwitcher.svelte";
+<script lang="ts">import { base } from "$app/paths";
+import ReviewThemeSwitcher from "./ReviewThemeSwitcher.svelte";
 import { reviewAppScenarios } from "./scenarios";
 let { data } = $props();
 const scenario = $derived(reviewAppScenarios[data.scenario]);
@@ -10,8 +11,8 @@ const scenario = $derived(reviewAppScenarios[data.scenario]);
 
 <div class="review-page-header">
   <div class="review-page-links">
-    <a href={`/svelte-contain-css/review/${data.theme}/`}>{data.themeLabel} routes</a>
-    <a href={`/svelte-contain-css/review/${data.theme}/app/`}>App scenarios</a>
+    <a href={`${base}/review/${data.theme}/`}>{data.themeLabel} routes</a>
+    <a href={`${base}/review/${data.theme}/app/`}>App scenarios</a>
   </div>
 
   <ReviewThemeSwitcher theme={data.theme} />

package/dist/review/ReviewRootIndex.svelte

@@ -1,4 +1,5 @@
-<script lang="ts">import ReviewIndexShell from "./ReviewIndexShell.svelte";
+<script lang="ts">import { base } from "$app/paths";
+import ReviewIndexShell from "./ReviewIndexShell.svelte";
 import { reviewThemeLabels } from "./themes";
 </script>
 
@@ -13,7 +14,7 @@ import { reviewThemeLabels } from "./themes";
   <ul>
     {#each Object.entries(reviewThemeLabels) as [theme, label]}
       <li>
-        <a href={`/svelte-contain-css/review/${theme}/`}>{label}</a>
+        <a href={`${base}/review/${theme}/`}>{label}</a>
       </li>
     {/each}
   </ul>

package/dist/review/ReviewThemeAppIndex.svelte

@@ -1,4 +1,5 @@
-<script lang="ts">import ReviewIndexShell from "./ReviewIndexShell.svelte";
+<script lang="ts">import { base } from "$app/paths";
+import ReviewIndexShell from "./ReviewIndexShell.svelte";
 import ReviewThemeSwitcher from "./ReviewThemeSwitcher.svelte";
 import { reviewAppScenarios } from "./scenarios";
 let { theme, themeLabel } = $props();
@@ -17,7 +18,7 @@ let { theme, themeLabel } = $props();
   <ul>
     {#each Object.entries(reviewAppScenarios) as [scenario, entry]}
       <li>
-        <a href={`/svelte-contain-css/review/${theme}/app/${scenario}`}>
+        <a href={`${base}/review/${theme}/app/${scenario}`}>
           {entry.title}
         </a>
       </li>

package/dist/review/ReviewThemeIndex.svelte

@@ -1,4 +1,5 @@
-<script lang="ts">import ReviewIndexShell from "./ReviewIndexShell.svelte";
+<script lang="ts">import { base } from "$app/paths";
+import ReviewIndexShell from "./ReviewIndexShell.svelte";
 import ReviewThemeSwitcher from "./ReviewThemeSwitcher.svelte";
 import { reviewAppScenarios } from "./scenarios";
 let { theme, themeLabel } = $props();
@@ -18,7 +19,7 @@ let { theme, themeLabel } = $props();
     <h2>Groups</h2>
     <ul>
       <li>
-        <a href={`/svelte-contain-css/review/${theme}/app/`}>App scenarios</a>
+        <a href={`${base}/review/${theme}/app/`}>App scenarios</a>
       </li>
     </ul>
   </section>
@@ -28,7 +29,7 @@ let { theme, themeLabel } = $props();
     <ul>
       {#each Object.entries(reviewAppScenarios) as [scenario, entry]}
         <li>
-          <a href={`/svelte-contain-css/review/${theme}/app/${scenario}`}>
+          <a href={`${base}/review/${theme}/app/${scenario}`}>
             {entry.title}
           </a>
         </li>

package/dist/review/ReviewThemeSwitcher.svelte

@@ -1,4 +1,5 @@
-<script lang="ts">import { page } from "$app/state";
+<script lang="ts">import { base } from "$app/paths";
+import { page } from "$app/state";
 import { reviewThemeLabels, reviewThemeNames, } from "./themes";
 let { theme } = $props();
 const themeLinks = $derived.by(() => {
@@ -16,7 +17,7 @@ const themeLinks = $derived.by(() => {
 </script>
 
 <nav class="review-theme-switcher" aria-label="Review theme switcher">
-  <a class="utility-link" href="/svelte-contain-css/review/">All Themes</a>
+  <a class="utility-link" href={`${base}/review/`}>All Themes</a>
 
   {#each themeLinks as item}
     <a

package/dist/sass/_affordances.scss

@@ -109,6 +109,33 @@
   }
 }
 
+// Focus ring for controls living inside an overflow:hidden container
+// (menus, tab bars). Drawn with a negative outline-offset so it sits inside
+// the control and is not clipped by the container. Defined after `clickable`
+// so `clickable-hover-affordance` is in scope.
+@mixin focus-ring-inset {
+  outline: var(--focus-color, -webkit-focus-ring-color) auto 1px;
+  outline-offset: var(--focus-inset-outline-offset, -3px);
+}
+
+// Clip-safe focus indicator: just the inset ring, no fill change. For
+// controls that already carry their own resting/active styling (tabs).
+@mixin focusable-inset($prefixes...) {
+  &:focus-visible {
+    @include focus-ring-inset();
+  }
+}
+
+// As `focusable-inset`, plus the hover affordance for the fill, so keyboard
+// focus reads the same as pointer hover. For controls with no resting
+// visual weight of their own (menu items).
+@mixin focusable-as-hover($prefixes...) {
+  &:focus-visible {
+    @include clickable-hover-affordance($prefixes...);
+    @include focus-ring-inset();
+  }
+}
+
 @mixin custom-scrollbar($prefixes...) {
   overflow-y: auto;
 

package/dist/vars/affordances.css

@@ -20,8 +20,14 @@
   --menu-item-hover-filter-custom: ;
   --menu-item-hover-filter: var(--menu-item-hover-filter-brightness-hack,)
     var(--menu-item-hover-filter-custom,);
-  /* Default menu items to the menu surface so row-wide filters read clearly. */
-  --menu-item-bg: var(--menu-bg, var(--bg));
+  /* NB: do NOT default --menu-item-bg here. Declared at :root it would freeze
+     to var(--bg) (--menu-bg is not set yet at :root) and then win the
+     color-props(menu-item, menu, ...) chain ahead of a per-instance --menu-bg,
+     breaking overrides like <Menu --menu-bg="#111">. The chain already ends at
+     --bg, and color-props now computes an always-opaque --_background-color on
+     the element (evaluated where --menu-bg is live), which the hover/active
+     filter affordances derive from -- so the "give filters an opaque surface"
+     goal is met structurally without a frozen root default. */
   --menu-item-active-filter-custom: ;
   --menu-item-active-filter: var(--menu-item-active-filter-custom,);
   /* --button-hover-transform: var(var(--button-hover-transform));

package/dist/vars/colors.css

@@ -36,7 +36,10 @@
   --surface-fg: var(--fg);
   --surface-link-fg: var(--link-fg, var(--primary-bg));
   --container-link-fg: var(--surface-link-fg);
-  --menu-item-bg: var(--menu-bg);
+  /* --menu-item-bg intentionally not defaulted at :root -- see the note in
+     affordances.css. The color-props(menu-item, menu, button, control) chain
+     resolves it to --menu-bg / --bg at the element, keeping per-instance
+     --menu-bg overrides working. */
   --focus-color: var(--material-color-blue-a400);
   --tooltip-border: none;
 }

package/dist/vars/defaults.css

@@ -63,7 +63,10 @@
   --surface-fg: var(--fg);
   --surface-link-fg: var(--link-fg, var(--primary-bg));
   --container-link-fg: var(--surface-link-fg);
-  --menu-item-bg: var(--menu-bg);
+  /* --menu-item-bg intentionally not defaulted at :root -- see the note in
+     affordances.css. The color-props(menu-item, menu, button, control) chain
+     resolves it to --menu-bg / --bg at the element, keeping per-instance
+     --menu-bg overrides working. */
   --focus-color: var(--material-color-blue-a400);
   --tooltip-border: none;
 }
@@ -424,8 +427,14 @@ a {
   --menu-item-hover-filter-custom: ;
   --menu-item-hover-filter: var(--menu-item-hover-filter-brightness-hack,)
     var(--menu-item-hover-filter-custom,);
-  /* Default menu items to the menu surface so row-wide filters read clearly. */
-  --menu-item-bg: var(--menu-bg, var(--bg));
+  /* NB: do NOT default --menu-item-bg here. Declared at :root it would freeze
+     to var(--bg) (--menu-bg is not set yet at :root) and then win the
+     color-props(menu-item, menu, ...) chain ahead of a per-instance --menu-bg,
+     breaking overrides like <Menu --menu-bg="#111">. The chain already ends at
+     --bg, and color-props now computes an always-opaque --_background-color on
+     the element (evaluated where --menu-bg is live), which the hover/active
+     filter affordances derive from -- so the "give filters an opaque surface"
+     goal is met structurally without a frozen root default. */
   --menu-item-active-filter-custom: ;
   --menu-item-active-filter: var(--menu-item-active-filter-custom,);
   /* --button-hover-transform: var(var(--button-hover-transform));

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "contain-css-svelte",
-  "version": "1.1.9",
+  "version": "1.1.11",
+  "license": "MIT",
   "scripts": {
     "capture:review": "node scripts/capture-review.mjs",
     "capture:review:matrix": "node scripts/capture-review-matrix.mjs",