Prepare 1.0.1 release

.github/workflows/discord-release.yml

@@ -0,0 +1,51 @@
+name: Announce release on Discord
+
+on:
+  release:
+    types: [published]
+
+permissions: {}
+
+jobs:
+  announce:
+    if: ${{ !github.event.release.prerelease }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Send Discord announcement
+        env:
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          RELEASE_NAME: ${{ github.event.release.name }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          RELEASE_URL: ${{ github.event.release.html_url }}
+          RELEASE_BODY: ${{ github.event.release.body }}
+          REPO: ${{ github.repository }}
+        run: |
+          test -n "$DISCORD_WEBHOOK_URL"
+
+          jq -n \
+            --arg repo "$REPO" \
+            --arg name "$RELEASE_NAME" \
+            --arg tag "$RELEASE_TAG" \
+            --arg url "$RELEASE_URL" \
+            --arg body "$RELEASE_BODY" \
+            '($body | if length > 1500 then .[:1500] + "...\n\n[Read more](" + $url + ")" else . end) as $description |
+            {
+              username: "Basecoat Releases",
+              allowed_mentions: { parse: [] },
+              embeds: [{
+                title: ($repo + " " + $tag),
+                url: $url,
+                description: ((if $name != "" then "**" + $name + "**\n\n" else "" end) + $description),
+                color: 5793266
+              }]
+            }' > payload.json
+
+          curl --fail-with-body \
+            --retry 3 \
+            --retry-all-errors \
+            --retry-delay 2 \
+            -H "Content-Type: application/json" \
+            -X POST \
+            -d @payload.json \
+            "$DISCORD_WEBHOOK_URL"

.gitignore

@@ -1,6 +1,10 @@
 .*
 !.gitignore
 !.gitattributes
+!.github/
+!.github/workflows/
+!.github/workflows/*.yml
+!.github/workflows/*.yaml
 _site/
 
 node_modules/

AGENTS.md

@@ -48,6 +48,7 @@
 ## JavaScript
 - JavaScript is behavior only; do not use JS to paper over CSS architecture issues.
 - Register JS components with `window.basecoat.register()` and make initialization idempotent with `data-*-initialized` flags.
+- Component init functions must return before attaching listeners or mutating DOM when the root already has its initialized flag.
 - Keep generated DOM minimal and aligned with documented HTML.
 - Prefer native browser APIs and events.
 - Keep scroll management scoped to component containers. Do not use `scrollIntoView()` when it can scroll the page unexpectedly.

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## [1.0.1] - 2026-06-28
+
+### Added
+
+- Added explicit `force: true` support to `window.basecoat.init()` and `window.basecoat.initAll()` for rehydrating restored DOM after framework or navigation cache restores.
+
+### Fixed
+
+- Reinitialized Basecoat components after HTMX history restores in the docs site.
+
 ## [1.0.0] - 2026-06-27
 
 ### Breaking Changes

README.md

@@ -92,6 +92,7 @@ These entrypoints are generated by `scripts/generate-css-entrypoints.js` and by
 
 - `window.basecoat.init(name)` initializes uninitialized components for one registered component.
 - `window.basecoat.initAll()` initializes all uninitialized registered components.
+- `window.basecoat.init(name, { force: true })` and `window.basecoat.initAll({ force: true })` destroy and reinitialize matching components. Use this when a framework or navigation library restores previously initialized DOM from a cache. Force mode resets transient component state such as open menus, focus state, and active interactions.
 - `window.basecoat.refresh(element)` asks an initialized component to rescan dynamic children when it supports refresh.
 - Components use internal destroy hooks to clean up listeners when initialized roots are removed from the DOM.
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "basecoat-css",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Tailwind CSS for Basecoat components",
   "author": {
     "name": "hunvreus",
@@ -123,12 +123,12 @@
   "scripts": {
     "build": "node ./scripts/build.js",
     "prepack": "node ./scripts/build.js",
-    "docs:build": "npm run build && npm --prefix site run build",
+    "docs:build": "npm run build && npm --prefix site clean-install --progress=false && npm --prefix site run build",
     "docs:dev": "npm --prefix site run dev",
     "docs:preview": "npm run docs:build && npm --prefix site run preview",
-    "workers:dev": "npm run build && npm --prefix site run workers:dev",
-    "workers:deploy": "npm run build && npm --prefix site run workers:deploy",
-    "workers:preview": "npm run build && npm --prefix site run workers:preview"
+    "workers:dev": "npm run build && npm --prefix site clean-install --progress=false && npm --prefix site run workers:dev",
+    "workers:deploy": "npm run build && npm --prefix site clean-install --progress=false && npm --prefix site run workers:deploy",
+    "workers:preview": "npm run build && npm --prefix site clean-install --progress=false && npm --prefix site run workers:preview"
   },
   "devDependencies": {
     "@tailwindcss/cli": "^4.1.17",

site/src/components/StyleHead.astro

@@ -159,7 +159,33 @@ const styleUrls = {
       }
     };
 
+    const clearSerializedRuntimeState = (root) => {
+      for (const element of root.querySelectorAll?.("*") || []) {
+        delete element.dataset.basecoatComponent;
+        for (const attribute of Array.from(element.attributes)) {
+          if (/^data-[a-z0-9-]+-initialized$/.test(attribute.name)) {
+            element.removeAttribute(attribute.name);
+          }
+        }
+      }
+    };
+
+    const cleanHistoryItem = (event) => {
+      const item = event.detail?.item;
+      if (typeof item?.content !== "string") return;
+
+      const template = document.createElement("template");
+      template.innerHTML = item.content;
+      clearSerializedRuntimeState(template.content);
+      item.content = template.innerHTML;
+    };
+
     document.addEventListener("DOMContentLoaded", syncSidebar);
+    document.addEventListener("htmx:historyItemCreated", cleanHistoryItem);
+    document.addEventListener("htmx:historyRestore", () => {
+      window.basecoat?.initAll?.({ force: true });
+      syncSidebar();
+    });
     document.addEventListener("htmx:afterSettle", () => {
       window.basecoat?.initAll?.();
       syncSidebar();

site/src/docs/installation.mdx

@@ -243,6 +243,14 @@ Chart uses a separate helper and is not included in `basecoat-css/all`.
 
 Each component page shows the minimal scripts or imports required for that component.
 
+### JavaScript lifecycle
+
+Basecoat initializes registered components on page load and when new DOM is inserted.
+
+Use `window.basecoat.initAll()` after manually inserting HTML that contains Basecoat components. It only initializes components that are not already initialized.
+
+Use `window.basecoat.initAll({ force: true })` when a framework or navigation library restores previously initialized DOM from a cache, such as an HTMX history restore. Force mode destroys existing component instances before reinitializing them, so it also resets transient state such as open menus, focus state, and active interactions.
+
 ## Compatibility
 
 Basecoat 1.0 introduces new style packs and a smaller public API based on root classes plus semantic HTML and documented attributes. If you need pre-1.0 class aliases while migrating, load the compatibility stylesheet after your Basecoat stylesheet.

site/src/scripts/demo-interactions.js

@@ -1,6 +1,3 @@
-import "../../../src/js/basecoat.js";
-import "../../../src/js/accordion.js";
-
 const initPriceRange = () => {
   const input = document.getElementById("price-range");
   const output = document.getElementById("price-range-output");
@@ -104,3 +101,5 @@ if (document.readyState === "loading") {
 } else {
   initDemos();
 }
+
+document.addEventListener("htmx:afterSettle", initDemos);

src/js/basecoat.js

@@ -63,9 +63,24 @@
     node.querySelectorAll('[data-basecoat-component]').forEach(destroyComponent);
   };
 
-  const initAllComponents = () => {
+  const uniqueElements = (elements) => Array.from(new Set(elements));
+
+  const getComponentElements = (componentName, selector, force = false) => {
+    const elements = Array.from(document.querySelectorAll(selector));
+    if (force) {
+      elements.push(...document.querySelectorAll(`[data-basecoat-component="${componentName}"]`));
+    }
+    return uniqueElements(elements);
+  };
+
+  const initAllComponents = (options = {}) => {
+    const force = options.force === true;
     Object.entries(componentRegistry).forEach(([name, { selector }]) => {
-      document.querySelectorAll(selector).forEach(element => initComponent(element, name));
+      getComponentElements(name, selector, force).forEach((element) => {
+        const wasComponent = element.dataset?.basecoatComponent === name;
+        if (force) destroyComponent(element);
+        if (wasComponent || element.matches(selector)) initComponent(element, name);
+      });
     });
   };
 
@@ -111,18 +126,23 @@
     observer = null;
   };
 
-  const initRegisteredComponent = (componentName) => {
+  const initRegisteredComponent = (componentName, options = {}) => {
     const component = componentRegistry[componentName];
     if (!component) {
       console.warn(`Component '${componentName}' not found in registry`);
       return;
     }
 
-    document.querySelectorAll(component.selector).forEach(element => initComponent(element, componentName));
+    const force = options.force === true;
+    getComponentElements(componentName, component.selector, force).forEach((element) => {
+      const wasComponent = element.dataset?.basecoatComponent === componentName;
+      if (force) destroyComponent(element);
+      if (wasComponent || element.matches(component.selector)) initComponent(element, componentName);
+    });
   };
 
-  const initAllRegisteredComponents = () => {
-    initAllComponents();
+  const initAllRegisteredComponents = (options = {}) => {
+    initAllComponents(options);
   };
 
   const setTheme = (mode) => {

src/js/sidebar.js

@@ -1,6 +1,6 @@
 (() => {
   const initSidebar = (sidebarComponent) => {
-    if (sidebarComponent.dataset.sidebarInitialized) return;
+    if (sidebarComponent.dataset.sidebarInitialized && typeof sidebarComponent.toggle === 'function') return;
 
     const initialOpen = sidebarComponent.dataset.initialOpen !== 'false';
     const initialMobileOpen = sidebarComponent.dataset.initialMobileOpen === 'true';
@@ -60,6 +60,6 @@
   };
 
   if (window.basecoat) {
-    window.basecoat.register('sidebar', '.sidebar:not([data-sidebar-initialized])', initSidebar);
+    window.basecoat.register('sidebar', '.sidebar', initSidebar);
   }
 })();