@jungherz-de/glasskit 1.3.4 → 1.4.0

package/CHANGELOG.md

@@ -7,17 +7,80 @@ GlassKit uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
-## [1.3.4] – 2026-03-29
+## [1.4.0] – 2026-04-11
 
 ### Added
 
+- **Two new components – `List` and `Popover`** – inspired by iOS 26 settings screens
+  - **`.glass-list`** – grouped settings-style container, visually based on `.glass-status` (`--gl-surface-1`, `--gl-blur-light`, `--gl-radius-btn`, subtle shadow)
+  - **`.glass-list__item`** – flexible row layout that scales from a single centered text (with ellipsis truncation) to a full settings row with leading icon, title + subtitle, and trailing element
+  - **List sub-elements**: `__leading` (28×28 icon slot), `__content` (flexible middle), `__title`, `__subtitle`, `__trailing` (chevron / value / button / badge)
+  - **List modifiers**: `--flush` (edge-to-edge variant), `--bare` (strips own glass surface for embedding inside `glass-popover` / `glass-card`), `__item--interactive` (hover / focus / active states), `__item--center` (centered single-text fallback)
+  - **Auto-rendered dividers** between list items via `::after` — no extra HTML markup required, last item automatically has no divider, and items without a leading icon get a standard horizontal padding inset (handled via `:has(.glass-list__leading)`)
+  - **`.glass-popover`** – anchored dropdown / menu container with fade + scale animation on `.is-open`
+  - **`.glass-popover-anchor`** – positioning context that wraps trigger + popover
+  - **Popover placement modifiers**: `--top` (opens upward), `--start` (left-aligned), `--end` (right-aligned); default placement is centered below the trigger
+- **Modal preview section** in `docs.html` and `de/docs.html` – previously the Modal section only had a class reference table; now it includes a live inline preview, full HTML code snippet with JS toggle functions, and an explicit note about putting `.is-active` on the overlay (not on `.glass-modal`)
+- **SKILL.md (AI reference) extensions**:
+  - New section **3.24 List** with copy-paste examples for both settings-style and compact-menu variants, full sub-element table, and SVG icon convention notes
+  - New section **3.25 Popover** with HTML + toggle JS, placement modifier reference, and explicit warning about the native API name collision
+  - New composition pattern **"iOS-style Settings Screen (List + Popover)"** – full example reproducing iOS settings layout with two grouped lists and an inline action menu
+  - State Classes Overview extended (`.is-open` now also for `.glass-popover`)
+  - Common Mistakes table extended with 4 new entries (manual divider markup, missing `--bare`, `togglePopover` naming clash, `.is-open` on the wrong element)
+  - "Always follow" rules extended with list-divider and popover-naming guidance
+  - Quick Class Reference table extended with List and Popover rows
+- **File size details** in `index.html` and `de/index.html` – the project file list now shows raw + gzipped sizes for `glasskit.css`, plus a dedicated row for `glasskit.min.css` (production build) with its own raw + gzipped sizes
+- **README.md "Lightweight" bullet** – now reports precise sizes (49 KB raw / 37 KB minified / 6.2 KB gzipped) instead of an approximate single number
+
+### Changed
+
+- **`bg-switcher` migration** in `showcase.html` and `de/showcase.html` – the ad-hoc popover originally embedded as inline CSS in the showcase has been removed and replaced with the new `.glass-popover` framework component, proving the new API works for the existing use case
+- **Component count** updated from **22 → 24** across all user-facing files: `index.html`, `docs.html`, `de/index.html`, `de/docs.html`, `package.json`, `README.md`, `SKILL.md`, and the `glasskit.css` header
+- **Sidebar navigation** in `docs.html` and `de/docs.html` extended with the new "List" link (under Content) and "Popover" link (under Actions)
+- **CDN version pinning** in `README.md` and `SKILL.md` updated from `@1.3` to `@1.4` for jsDelivr (minified + unminified) and unpkg
+- **English consistency in `glasskit.css`** – the remaining German comments in the source file have been translated to English (`Farben`, `Glas-Oberflächen`, `Icon-Farben`, `Hintergrund-Effekte`, `Toggle (inaktiv)`, `Größen`, `22 Komponenten`, plus the multi-line comments in the new List section)
+- **Showcase title** in `showcase.html` and `de/showcase.html` bumped to `v1.4.0`
+- **Version stamps** updated to `1.4.0` in `package.json`, README badges, `glasskit.css` header, sidebar versions, and hero badges (English + German)
+
+### Fixed
+
+- **List divider inset for icon-less items** – when a `.glass-list__item` has no leading icon, the auto-divider now uses the standard horizontal padding (`var(--gl-space-lg)` left + right) instead of blindly inheriting the icon-aligned 60px inset. Detected via `:has(.glass-list__leading)`.
+- **List divider right-edge alignment** – the divider used to extend all the way to the right edge of the item (`right: 0`), past where the trailing element ends. It now stops at `var(--gl-space-lg)` so it lines up flush with the trailing slot.
+- **`togglePopover` naming clash** – discovered during showcase migration: a custom JS function named `togglePopover` collides with the native `HTMLElement.togglePopover()` method (HTML Popover API) and inline `onclick` handlers throw `NotSupportedError`. The showcase / docs JS toggles were renamed to `gkTogglePopover` / `docsTogglePopover`, and the gotcha is documented in `SKILL.md`, the docs Popover section, and this changelog.
+
+### Notes
+
+- **No breaking changes.** All additions are additive; existing markup continues to work unchanged.
+- **`glass-divider` is unchanged.** The new list dividers are scoped to `.glass-list__item::after` and do not affect or replace the global `.glass-divider` element (which keeps its gradient-fade visual style).
+- **`:has()` selector requirement** – the icon-aware divider rule uses CSS `:has()`, which is supported in all modern evergreen browsers (Chrome 105+, Safari 15.4+, Firefox 121+, ~95% global as of 2026). Lists with mixed-icon items will fall back gracefully (icon-less items get the icon-aligned inset, which is visually fine, just slightly more right-shifted than ideal).
+
+---
+
+## [1.3.5] – 2026-04-04
+
+### Added
+
+- **`SKILL.md` – AI-optimized component reference** – a structured, machine-readable reference document designed for LLMs, AI copilots, and code-generation tools
+  - Copy-paste-ready HTML for all 22 components with exact nesting and BEM hierarchy
+  - Complete design token tables (colors, surfaces, borders, blur, radii, spacing, shadows, typography)
+  - State class reference – clear mapping of `is-active`, `is-open`, `is-visible`, `:checked`, `:focus`, `:disabled` to their components
+  - 6 composition patterns – full page layouts: Login, Dashboard, Form, Modal confirmation, Settings, Progress + Toast
+  - Common mistakes & corrections table – prevents frequent AI-generated errors
+  - Quick reference table – all components with modifiers at a glance
+  - Utility class reference with exact gap/margin values
+  - Web Components / Shadow DOM usage guide
+  - Custom theming instructions
 - **Visual preview for Tab-Bar** in `docs.html` and `de/docs.html` – live rendered tab bar with 4 tabs (Home, Documents with badge, Upload, Settings)
 - **Visual preview for Toast** in `docs.html` and `de/docs.html` – static success toast rendered inline
 - **HTML code example for Status Notice** in `docs.html` and `de/docs.html` – was previously preview-only without code snippet
 
 ### Changed
 
-- Version references updated to 1.3.4 across all files
+- **README.md** – new “AI / LLM Reference” section documenting `SKILL.md` purpose and usage, “AI-ready” added to “Why GlassKit?”
+- **Project structure** in README updated to include `SKILL.md`
+- **docs.html & de/docs.html** – new “AI Reference” / “KI-Referenz” section with sidebar link
+- **index.html & de/index.html** – SKILL.md added to project file list
+- Version references updated to 1.3.5 across all files
 
 ---
 
@@ -207,9 +270,11 @@ during development. Version 1.3 is the first public open-source release.
 
 ---
 
+[1.4.0]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.4.0
+[1.3.5]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.3.5
 [1.3.4]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.3.4
 [1.3.3]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.3.3
 [1.3.2]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.3.2
 [1.3.1]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.3.1
 [1.3.0]: https://github.com/JUNGHERZ/GlassKit/releases/tag/v1.3.0
-[Unreleased]: https://github.com/JUNGHERZ/GlassKit/compare/v1.3.4...HEAD
+[Unreleased]: https://github.com/JUNGHERZ/GlassKit/compare/v1.4.0...HEAD

package/README.md

@@ -1,9 +1,9 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-1.3.4-orange?style=flat-square" alt="Version">
+  <img src="https://img.shields.io/badge/version-1.4.0-orange?style=flat-square" alt="Version">
   <img src="https://img.shields.io/badge/CSS-only-blue?style=flat-square" alt="CSS only">
-  <img src="https://img.shields.io/badge/components-22-green?style=flat-square" alt="Components">
+  <img src="https://img.shields.io/badge/components-24-green?style=flat-square" alt="Components">
   <img src="https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square" alt="License">
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-v1.3.4-f5a623?style=flat-square" alt="Changelog"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-v1.4.0-f5a623?style=flat-square" alt="Changelog"></a>
   <a href="https://www.npmjs.com/package/@jungherz-de/glasskit"><img src="https://img.shields.io/npm/v/@jungherz-de/glasskit?style=flat-square&color=cb3837&label=npm" alt="npm"></a>
   <a href="https://cdn.jsdelivr.net/npm/@jungherz-de/glasskit/"><img src="https://img.shields.io/badge/CDN-jsDelivr-blue?style=flat-square" alt="jsDelivr"></a>
 </p>
@@ -16,7 +16,7 @@
 
 <p align="center">
   <strong>A modern glassmorphism CSS component library.</strong><br>
-  22 Components · Dark & Light Mode · No Dependencies · Design Tokens
+  24 Components · Dark & Light Mode · No Dependencies · Design Tokens
 </p>
 
 <p align="center">
@@ -48,8 +48,9 @@ GlassKit is a complete **CSS component library** with glassmorphism aesthetics
 - 📱 **Mobile-first** – optimized for touch devices and `safe-area-inset`
 - 🔌 **Framework-agnostic** – works with React, Vue, Svelte, plain HTML, or any other stack
 - 🧩 **Shadow DOM ready** – Constructable Stylesheet for Web Components included
-- 🪶 **Lightweight** – ~45 KB (uncompressed), no external dependencies
+- 🪶 **Lightweight** – 49 KB raw / 37 KB minified / 6.2 KB gzipped, no external dependencies
 - 🎯 **BEM-like naming convention** – `glass-*` prefix, no conflicts with existing CSS
+- 🤖 **AI-ready** – ships with [`SKILL.md`](SKILL.md), a structured reference for LLMs & AI copilots
 
 ---
 
@@ -63,16 +64,16 @@ No download, no build tool – just include and go:
 
 ```html
 <!-- jsDelivr – Minified -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/glasskit@1.3/glasskit.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/glasskit@1.4/glasskit.min.css">
 
 <!-- jsDelivr – Unminified (for reading/debugging) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/glasskit@1.3/glasskit.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/glasskit@1.4/glasskit.css">
 
 <!-- unpkg – Alternative -->
-<link rel="stylesheet" href="https://unpkg.com/@jungherz-de/glasskit@1.3/glasskit.min.css">
+<link rel="stylesheet" href="https://unpkg.com/@jungherz-de/glasskit@1.4/glasskit.min.css">
 ```
 
-> **Tip:** Replace `@1.3` with `@latest` for the newest version – or pin to a specific version for maximum stability.
+> **Tip:** Replace `@1.4` with `@latest` for the newest version – or pin to a specific version for maximum stability.
 
 ### npm / yarn / pnpm
 
@@ -176,6 +177,7 @@ Download the files directly from the [GitHub Release](https://github.com/JUNGHER
 | **Badge** | `.glass-badge` | Tags & labels |
 | **Avatar** | `.glass-avatar` | Glass circle (sm/md/lg) |
 | **Status** | `.glass-status` | Notice card with icon |
+| **List** | `.glass-list` | iOS-style grouped settings list with auto dividers |
 
 ### Actions & Feedback
 
@@ -186,6 +188,7 @@ Download the files directly from the [GitHub Release](https://github.com/JUNGHER
 | **Button (Tertiary)** | `.glass-btn--tertiary` | Subtle glass – tertiary action |
 | **Modal** | `.glass-modal` | Centered dialog with blur overlay |
 | **Toast** | `.glass-toast` | Temporary notification |
+| **Popover** | `.glass-popover` | Anchored dropdown / menu with fade & scale animation |
 
 ### Form Elements
 
@@ -428,6 +431,7 @@ glasskit/
 ├── showcase.html           # Interactive showcase of all components
 ├── docs.html               # Full documentation
 ├── de/                     # German translations (index, docs, showcase)
+├── SKILL.md                 # AI-optimized component reference (for LLMs & copilots)
 ├── LICENSE                  # MIT License
 └── README.md               # This file
 ```
@@ -438,7 +442,7 @@ glasskit/
 
 The full documentation with **live previews**, **copy-paste code blocks**, and **class reference tables** is available in `docs.html`:
 
-- Sidebar navigation to all 22 components
+- Sidebar navigation to all 24 components
 - Live previews on a real glassmorphism background
 - Design token reference
 - Theming guide
@@ -462,6 +466,27 @@ Useful links:
 
 ---
 
+## 🤖 AI / LLM Reference (`SKILL.md`)
+
+GlassKit ships with an **AI-optimized component reference** in [`SKILL.md`](SKILL.md). This file is designed for LLMs, AI copilots, and code-generation tools to produce correct GlassKit markup without parsing `docs.html`.
+
+### What it provides
+
+- **Copy-paste-ready HTML** for all 24 components with exact nesting rules
+- **Complete design token tables** (colors, surfaces, blur, radii, spacing, shadows, typography)
+- **State class reference** – which class goes where (`is-active`, `is-open`, `is-visible`, `:checked`)
+- **6 composition patterns** – full page layouts (Login, Dashboard, Form, Modal, Settings, Progress)
+- **Common mistakes & corrections** – prevents the most frequent AI-generated errors
+- **Quick reference table** – all components with their modifiers at a glance
+
+### Usage with AI assistants
+
+Attach or reference `SKILL.md` when asking an AI to generate GlassKit HTML. It provides the structured context needed for production-ready output – correct BEM hierarchy, proper modifier usage, and idiomatic component composition.
+
+> **Tip:** While `docs.html` is built for humans browsing with live previews, `SKILL.md` is built for machines generating code. Both are kept in sync.
+
+---
+
 ## 🌐 Browser Compatibility
 
 GlassKit uses `backdrop-filter` for glass effects. Support:
@@ -482,7 +507,7 @@ GlassKit uses `backdrop-filter` for glass effects. Support:
 ```
 Interactive States:
   .is-active          → Tab Bar item, Modal Overlay
-  .is-open            → Accordion item
+  .is-open            → Accordion item, Popover
   .is-visible         → Toast
   :checked            → Toggle, Checkbox, Radio
   :focus              → Input, Textarea, Select, Range
@@ -511,6 +536,13 @@ Toast Modifiers:
 Modal Action Modifiers:
   .glass-modal__action--primary / --danger
 
+List Modifiers:
+  .glass-list--flush / --bare
+  .glass-list__item--interactive / --center
+
+Popover Modifiers:
+  .glass-popover--top / --start / --end
+
 Background Modifiers:
   .glass-bg--has-tab-bar
 ```