bulma-turbo-themes 0.8.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 812fdf4e99d1579e7b6c84f3238ee761181eb6b091629430e53e4156171c438c
-  data.tar.gz: 600afaa907a3247f7cd3c57348b7af8411aa483bbe3a7bc676cf3f83247e6db1
+  metadata.gz: ff3e634c80638ad6f5ad69a6568635a472228a2b816bda3823b292385726c038
+  data.tar.gz: 67c0c52ea8a2b2d5d8126d5a89cda1753d454c5a65e0082fcb15db368e6e8097
 SHA512:
-  metadata.gz: a1ee5f3bdc8e41f475a910208a8d163004b30697925b87d80f3a2e978b63b55207dc26c77017f0fde62d12e3a49391c9f3d39e7858e7c1cc3b1d6269e4118a11
-  data.tar.gz: ff997a38ad1069972b6cf2e6316c984d459d68633b2196f71f3dd0bfea9331973c92259a4e4994aab2568abd5b317180d7e7d642e08a650fa5055b7b0e621759
+  metadata.gz: 518dc0c638a69003056143e7f466bed724f93f5bee8929e65d7712710b4c795b900368ca26668529b2cf661a1ac0d80df235f34c7336a4067e14683075f5644c
+  data.tar.gz: ea9a920d193c8968501184afc433c13e9de6f113969289175d0dd57fda5ad9f5aa2b28817612d6a526bc8517f038f4c0bbd427e9275314b4f2d038157d84202c

data/CHANGELOG.md

@@ -10,6 +10,36 @@ The format is based on Keep a Changelog and this project adheres to SemVer.
 
 - TBD
 
+## [0.10.0] - 2025-12-05
+
+### ✨ Added
+
+- add full theming solution with context and hooks (#151)
+
+### 🐛 Fixed
+
+- recognize scoped conventional commits in version bump (#154)
+- update peter-evans/create-pull-request action to v7.0.11 (#148)
+- add missing egress endpoints for Bun CDN downloads
+
+## [0.9.0] - 2025-12-05
+
+### ✨ Added
+
+- migrate theme system to SASS (#143)
+
+### 🐛 Fixed
+
+- enable platformCommit for Renovate to sign commits
+- correct JavaScript reference in gem layout (#106)
+
+### 🔧 Changed
+
+- add missing egress endpoints for Bun download (#149)
+- update actions/setup-node digest to 633bb92 (#110)
+- update peter-evans/create-pull-request digest to 271a8d0 (#109)
+- update actions/setup-node digest to 2028fbc (#108)
+
 ## [0.8.1] - 2025-11-16
 
 ### 🐛 Fixed

data/README.md

@@ -2,6 +2,7 @@
 
 Modern, accessible theme packs and a drop-in theme selector for Bulma 1.x.
 
+[![Bun](https://img.shields.io/badge/bun-1.3+-black?logo=bun)](https://bun.sh/)
 [![Node.js](https://img.shields.io/badge/node.js-22-green)](https://nodejs.org/)
 [![Coverage](https://codecov.io/gh/TurboCoder13/bulma-turbo-themes/branch/main/graph/badge.svg)](https://codecov.io/gh/TurboCoder13/bulma-turbo-themes)
 [![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
@@ -23,6 +24,9 @@ Modern, accessible theme packs and a drop-in theme selector for Bulma 1.x.
 - Accessible theme selector with keyboard and screen reader support
 - Inline or link-based CSS delivery; CSP-friendly
 - Tested with coverage, Lighthouse CI, and stylelint
+- Advanced Bulma customization (breakpoints, spacing, shadows, mixins)
+- Lazy-loaded themes with performance optimizations
+- Full Bulma Sass variable integration
 
 ## Installation
 
@@ -49,11 +53,19 @@ bundle exec jekyll serve
 
 Assets are automatically available - no copying needed!
 
+### Advanced Theming
+
+For advanced customization options including custom breakpoints, spacing, shadows, and Bulma mixins, see the [Advanced Theming Guide](docs/ADVANCED-THEMING.md).
+
 ### For Non-Jekyll Projects
 
-Install via npm:
+Install via Bun (recommended) or npm:
 
 ```bash
+# Using Bun (recommended - 5-10x faster)
+bun add @turbocoder13/bulma-turbo-themes
+
+# Using npm
 npm install @turbocoder13/bulma-turbo-themes
 ```
 
@@ -76,18 +88,24 @@ npm install @turbocoder13/bulma-turbo-themes
 1. Add selector markup and initialize:
 
 ```html
-<div class="dropdown is-right is-theme" id="theme-flavor-dd">
-  <div class="dropdown-trigger">
-    <button id="theme-flavor-trigger" aria-haspopup="true">
-      <span id="theme-flavor-trigger-icon"></span>
-      <span id="theme-flavor-trigger-label"></span>
-    </button>
-  </div>
-  <div class="dropdown-menu" id="theme-flavor-menu" role="menu">
+<div class="navbar-item has-dropdown is-hoverable">
+  <button
+    class="navbar-link"
+    id="theme-flavor-trigger"
+    type="button"
+    aria-haspopup="true"
+    aria-expanded="false"
+    aria-controls="theme-flavor-menu"
+  >
+    <span class="icon is-small" id="theme-flavor-trigger-icon"></span>
+    Theme
+  </button>
+  <div class="navbar-dropdown" id="theme-flavor-menu" aria-labelledby="theme-flavor-trigger">
     <div class="dropdown-content" id="theme-flavor-items"></div>
   </div>
-  <div class="select is-hidden"><select id="theme-flavor-select"></select></div>
-  <span id="theme-flavor-icon"></span>
+</div>
+<div class="select is-rounded is-small is-hidden">
+  <select id="theme-flavor-select" aria-label="Theme flavor" disabled></select>
 </div>
 ```
 
@@ -110,18 +128,24 @@ npm install @turbocoder13/bulma-turbo-themes
 1. Add selector markup and initialize:
 
 ```html
-<div class="dropdown is-right is-theme" id="theme-flavor-dd">
-  <div class="dropdown-trigger">
-    <button id="theme-flavor-trigger" aria-haspopup="true">
-      <span id="theme-flavor-trigger-icon"></span>
-      <span id="theme-flavor-trigger-label"></span>
-    </button>
-  </div>
-  <div class="dropdown-menu" id="theme-flavor-menu" role="menu">
+<div class="navbar-item has-dropdown is-hoverable">
+  <button
+    class="navbar-link"
+    id="theme-flavor-trigger"
+    type="button"
+    aria-haspopup="true"
+    aria-expanded="false"
+    aria-controls="theme-flavor-menu"
+  >
+    <span class="icon is-small" id="theme-flavor-trigger-icon"></span>
+    Theme
+  </button>
+  <div class="navbar-dropdown" id="theme-flavor-menu" aria-labelledby="theme-flavor-trigger">
     <div class="dropdown-content" id="theme-flavor-items"></div>
   </div>
-  <div class="select is-hidden"><select id="theme-flavor-select"></select></div>
-  <span id="theme-flavor-icon"></span>
+</div>
+<div class="select is-rounded is-small is-hidden">
+  <select id="theme-flavor-select" aria-label="Theme flavor" disabled></select>
 </div>
 ```
 
@@ -134,6 +158,93 @@ document.addEventListener('DOMContentLoaded', () => {
 });
 ```
 
+### React Native / Cross-Platform
+
+This package provides platform-agnostic design tokens that work in React Native, Expo, and other non-web environments.
+
+#### Installation
+
+```bash
+bun add @turbocoder13/bulma-turbo-themes
+# or
+npm install @turbocoder13/bulma-turbo-themes
+```
+
+#### Basic Usage (Without Context)
+
+```tsx
+import { useTheme, useThemeColors } from '@turbocoder13/bulma-turbo-themes/tokens/react-native';
+
+function MyComponent() {
+  const { colors, styles, theme } = useTheme('catppuccin-mocha');
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.h1}>{theme.label}</Text>
+      <Text style={[styles.text, { color: colors.brandPrimary }]}>
+        Primary color text
+      </Text>
+    </View>
+  );
+}
+```
+
+#### With ThemeProvider (Recommended)
+
+```tsx
+import { ThemeProvider, useThemeContext } from '@turbocoder13/bulma-turbo-themes/tokens/react-native';
+import { useColorScheme } from 'react-native';
+
+// Wrap your app with ThemeProvider
+function App() {
+  return (
+    <ThemeProvider
+      useColorScheme={useColorScheme}
+      followSystem
+      lightTheme="catppuccin-latte"
+      darkTheme="catppuccin-mocha"
+    >
+      <MyApp />
+    </ThemeProvider>
+  );
+}
+
+// Use the theme in any component
+function MyApp() {
+  const { colors, styles, setTheme, toggleAppearance, appearance } = useThemeContext();
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.h1}>Welcome!</Text>
+      <Button
+        title={`Switch to ${appearance === 'dark' ? 'light' : 'dark'}`}
+        onPress={toggleAppearance}
+      />
+    </View>
+  );
+}
+```
+
+#### Available Exports
+
+| Import Path | Use Case |
+|-------------|----------|
+| `@turbocoder13/bulma-turbo-themes/tokens` | Platform-agnostic tokens (pure data) |
+| `@turbocoder13/bulma-turbo-themes/tokens/react-native` | React Native utilities, hooks, and context |
+| `@turbocoder13/bulma-turbo-themes/tokens.json` | JSON tokens for Flutter, Swift, Kotlin |
+| `@turbocoder13/bulma-turbo-themes/css/*` | CSS files for web |
+
+#### Pre-built Styles
+
+The React Native module includes pre-built styles for common components:
+
+- **Layout**: `container`, `safeArea`, `centered`, `row`
+- **Typography**: `h1`-`h6`, `text`, `textSecondary`, `caption`, `label`, `link`
+- **Components**: `card`, `cardElevated`, `button`, `buttonOutline`, `input`, `listItem`, `badge`, `tag`, `divider`
+- **State Colors**: `success`, `warning`, `danger`, `info`
+
+Plus design tokens for `spacing`, `typography`, `borderRadius`, and `shadows`.
+
 ## Testing
 
 This project includes comprehensive testing:
@@ -146,16 +257,53 @@ This project includes comprehensive testing:
 Run tests:
 
 ```bash
+# Using Bun (recommended)
+bun run test          # Unit tests with coverage
+bun run e2e           # All E2E tests
+bun run e2e:smoke     # Smoke tests only
+bun run e2e:visual    # Visual regression tests
+bun run e2e:a11y      # Accessibility tests
+bun run e2e:ui        # Playwright UI mode
+
+# Using npm (also works)
 npm test              # Unit tests with coverage
 npm run e2e           # All E2E tests
-npm run e2e:smoke     # Smoke tests only
-npm run e2e:visual    # Visual regression tests
-npm run e2e:a11y      # Accessibility tests
-npm run e2e:ui        # Playwright UI mode
 ```
 
 For detailed E2E testing documentation, see `docs/E2E-TESTING.md`.
 
+## Development Setup
+
+### Prerequisites
+
+- **Bun** 1.3+ (recommended) - [Install Bun](https://bun.sh/docs/installation)
+- **Node.js** 22+ (alternative)
+- **Ruby** 3.3+ with Bundler (for Jekyll demo site)
+
+### Quick Start
+
+```bash
+# Clone and install
+git clone https://github.com/TurboCoder13/bulma-turbo-themes.git
+cd bulma-turbo-themes
+bun install
+bundle install
+
+# Build and serve
+bun run build
+bun run build:themes
+bun run serve
+```
+
+### Why Bun?
+
+This project uses [Bun](https://bun.sh/) as its primary JavaScript runtime for:
+
+- **5-10x faster** package installation
+- **10x faster** script startup time
+- **~40% reduction** in CI build times
+- Full npm compatibility (works with all existing packages)
+
 ## Documentation
 
 - Code of Conduct: see `CODE_OF_CONDUCT.md`

data/_layouts/default.html

@@ -8,15 +8,108 @@
       data-theme-label="{{ site.data.i18n.en.theme_label }}"
       data-current-theme-title-template="{{ site.data.i18n.en.current_theme_title }}"
     />
+    <!--
+      CSP Security Trade-off: 'unsafe-inline' for script-src
+      ========================================================
+      Why required: The inline theme-blocking script (lines 19-87 below) must run
+      synchronously before first paint to prevent Flash of Unstyled Content (FOUC).
+      Without it, users would see the wrong theme briefly before it snaps to their
+      saved preference — a jarring experience.
+
+      Why not use nonces/hashes:
+      - Nonces require server-side generation (not possible with static Jekyll/GitHub Pages)
+      - Hashes are brittle and break on any script change, causing CI failures
+
+      Mitigations in place:
+      - Inline script validates theme IDs against allowlist (prevents class injection)
+      - URL sanitization prevents XSS via manipulated data-baseurl
+      - No eval() or dynamic code execution
+      - All other scripts are external files
+
+      Future tightening: Service worker precomputed theme class, or migration to SSR
+      with nonce-based CSP.
+
+      See: docs/adr/0004-csp-unsafe-inline-for-theme-blocking-script.md
+    -->
+    <!-- Note: frame-ancestors can only be set via HTTP header, not meta tag, so it's omitted here -->
     <meta
       http-equiv="Content-Security-Policy"
-      content="default-src 'self'; script-src 'self'; style-src 'self' https://cdn.jsdelivr.net https://fonts.googleapis.com; img-src 'self' data:; font-src 'self' https://fonts.gstatic.com data:; connect-src 'self' https://cdn.jsdelivr.net https://fonts.googleapis.com https://fonts.gstatic.com; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'self'; upgrade-insecure-requests"
+      content="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; img-src 'self' data:; font-src 'self' https://fonts.gstatic.com data:; connect-src 'self' https://fonts.googleapis.com https://fonts.gstatic.com; object-src 'none'; base-uri 'self'; form-action 'self'; upgrade-insecure-requests"
     />
     <title>{{ page.title | default: site.title }}</title>
     {% seo %}
+    <!-- Blocking script to apply theme immediately from localStorage -->
+    <!-- This prevents FOUC by setting theme class before first paint -->
+    <script>
+      (function () {
+        try {
+          var STORAGE_KEY = 'bulma-theme-flavor';
+          var DEFAULT_THEME = 'catppuccin-mocha';
+          // Valid theme IDs - must match THEMES array in theme-selector.js
+          var VALID_THEMES = [
+            'bulma-light',
+            'bulma-dark',
+            'catppuccin-latte',
+            'catppuccin-frappe',
+            'catppuccin-macchiato',
+            'catppuccin-mocha',
+            'dracula',
+            'github-light',
+            'github-dark',
+          ];
+          var savedTheme = localStorage.getItem(STORAGE_KEY) || DEFAULT_THEME;
+          // Validate theme ID against allowed list to prevent invalid class/URL injection
+          if (VALID_THEMES.indexOf(savedTheme) === -1) {
+            savedTheme = DEFAULT_THEME;
+          }
+          var themeClass = 'theme-' + savedTheme;
+
+          // Apply theme class using classList to preserve existing classes
+          // First remove any existing theme classes
+          var classList = document.documentElement.classList;
+          var classesToRemove = [];
+          for (var i = 0; i < classList.length; i++) {
+            if (classList[i].indexOf('theme-') === 0) {
+              classesToRemove.push(classList[i]);
+            }
+          }
+          classesToRemove.forEach(function (cls) {
+            classList.remove(cls);
+          });
+          // Add the new theme class
+          classList.add(themeClass);
+
+          // Preload theme CSS for faster loading
+          var baseUrl = document.documentElement.getAttribute('data-baseurl') || '';
+          // Sanitize baseUrl to prevent XSS attacks
+          function sanitizeUrlPath(path) {
+            if (!path) return '';
+            // Remove or encode dangerous characters that could be interpreted as HTML/JS
+            return path.replace(/[<>"'`&]/g, '').replace(/\\/g, '');
+          }
+          var sanitizedBaseUrl = sanitizeUrlPath(baseUrl);
+          // Resolve path relative to site root
+          var base = sanitizedBaseUrl
+            ? window.location.origin + sanitizedBaseUrl + '/'
+            : window.location.origin + '/';
+          var themePath = new URL('assets/css/themes/' + savedTheme + '.css', base).pathname;
+
+          // Create preload link
+          var preloadLink = document.createElement('link');
+          preloadLink.rel = 'preload';
+          preloadLink.as = 'style';
+          preloadLink.href = themePath;
+          document.head.appendChild(preloadLink);
+
+          // Store theme info for later use
+          window.__INITIAL_THEME__ = savedTheme;
+        } catch (e) {
+          // Silently fail if localStorage is not available
+          console.warn('Unable to load saved theme:', e);
+        }
+      })();
+    </script>
     <link rel="icon" href="{{ '/favicon.ico' | relative_url }}" />
-    <link rel="dns-prefetch" href="https://cdn.jsdelivr.net" />
-    <link rel="preconnect" href="https://cdn.jsdelivr.net" crossorigin />
     <link
       rel="icon"
       type="image/png"
@@ -34,32 +127,51 @@
       href="{{ '/assets/img/bulma-logo.png' | relative_url }}"
       color="#111827"
     />
+    <!--
+      Critical CSS removed - was causing theme override issues.
+      Theme CSS uses CSS variables for colors, but hardcoded critical CSS
+      was overriding them. The theme CSS is preloaded for fast loading.
+    -->
+    <!-- Base CSS (shared styles, loaded asynchronously) -->
     <link
+      id="theme-base-css"
       rel="preload"
       as="style"
-      href="https://cdn.jsdelivr.net/npm/bulma@1.0.2/css/bulma.min.css"
-      crossorigin="anonymous"
-    />
-    <link
-      rel="stylesheet"
-      href="https://cdn.jsdelivr.net/npm/bulma@1.0.2/css/bulma.min.css"
-      integrity="sha384-tl5h4XuWmVzPeVWU0x8bx0j/5iMwCBduLEgZ+2lH4Wjda+4+q3mpCww74dgAB3OX"
-      crossorigin="anonymous"
+      href="{{ '/assets/css/themes/base.css' | relative_url }}"
+      onload="this.rel = 'stylesheet'"
     />
-    <link
-      id="theme-global-css"
-      rel="stylesheet"
-      href="{{ '/assets/css/themes/global.css' | relative_url }}"
-    />
-    <link id="theme-flavor-css" rel="stylesheet" href="#" />
+    <noscript>
+      <link rel="stylesheet" href="{{ '/assets/css/themes/base.css' | relative_url }}" />
+    </noscript>
     <link rel="stylesheet" href="{{ '/assets/css/custom.css' | relative_url }}" />
-    <script type="module" src="{{ '/dist/index.js' | relative_url }}"></script>
+    <!-- Use minified JS in production for ~50% smaller payload -->
+    {% if jekyll.environment == 'production' %}
+    <script type="module" src="{{ '/assets/js/theme-selector.min.js' | relative_url }}"></script>
+    {% else %}
+    <script type="module" src="{{ '/assets/js/theme-selector.js' | relative_url }}"></script>
+    {% endif %}
     <script>
       document.addEventListener('DOMContentLoaded', () => {
         // Initialize navbar highlighting
         if (window.initNavbar) {
           window.initNavbar(document);
         }
+
+        // Initialize burger menu toggle
+        const burgers = document.querySelectorAll('.navbar-burger');
+        burgers.forEach((burger) => {
+          burger.addEventListener('click', () => {
+            const targetId = burger.dataset.target;
+            const target = document.getElementById(targetId);
+            if (target) {
+              burger.classList.toggle('is-active');
+              target.classList.toggle('is-active');
+              // Update aria-expanded
+              const isExpanded = burger.classList.contains('is-active');
+              burger.setAttribute('aria-expanded', String(isExpanded));
+            }
+          });
+        });
       });
     </script>
   </head>
@@ -212,43 +324,38 @@
             </div>
           </div>
           <div class="navbar-end">
-            <div class="navbar-item">
-              <div class="control has-icons-left">
-                <div class="select is-rounded is-small is-hidden" aria-hidden="true">
-                  <select id="theme-flavor-select" aria-label="Theme flavor" disabled></select>
-                </div>
-                <span
-                  class="icon is-small is-left"
-                  id="theme-flavor-icon"
-                  aria-hidden="true"
-                ></span>
-              </div>
+            <div class="navbar-item has-dropdown is-hoverable" data-testid="theme-dropdown">
+              <button
+                class="theme-trigger-icon"
+                id="theme-flavor-trigger"
+                type="button"
+                aria-haspopup="true"
+                aria-expanded="false"
+                aria-controls="theme-flavor-menu"
+                aria-label="Select theme"
+                data-testid="theme-trigger"
+              >
+                <img
+                  id="theme-flavor-trigger-icon"
+                  src="{{ '/assets/img/catppuccin-logo-macchiato.png' | relative_url }}"
+                  alt="Current theme"
+                  width="32"
+                  height="32"
+                />
+              </button>
               <div
-                class="dropdown is-right is-theme"
-                id="theme-flavor-dd"
-                data-testid="theme-dropdown"
+                class="navbar-dropdown is-right"
+                id="theme-flavor-menu"
+                aria-labelledby="theme-flavor-trigger"
+                data-testid="theme-menu"
+                role="menu"
               >
-                <div class="dropdown-trigger">
-                  <button
-                    class="button is-small is-rounded is-flavor-trigger theme-flavor-trigger"
-                    aria-haspopup="true"
-                    aria-controls="theme-flavor-menu"
-                    aria-label="Theme"
-                    data-testid="theme-trigger"
-                  >
-                    <span class="icon is-small" id="theme-flavor-trigger-icon"></span>
-                  </button>
-                </div>
-                <div
-                  class="dropdown-menu"
-                  id="theme-flavor-menu"
-                  role="menu"
-                  data-testid="theme-menu"
-                >
-                  <div class="dropdown-content" id="theme-flavor-items"></div>
-                </div>
+                <!-- Theme items populated by JS -->
               </div>
             </div>
+            <div class="select is-rounded is-small is-hidden">
+              <select id="theme-flavor-select" aria-label="Theme flavor" disabled></select>
+            </div>
           </div>
         </div>
       </div>

data/assets/css/custom.css

@@ -30,3 +30,33 @@
   width: 1rem;
   height: 1rem;
 }
+
+/* Theme switch loading indicator */
+
+.theme-flavor-trigger.is-loading {
+  opacity: 0.7;
+  pointer-events: none;
+  position: relative;
+}
+
+.theme-flavor-trigger.is-loading::after {
+  content: '';
+  position: absolute;
+  width: 16px;
+  height: 16px;
+  top: 50%;
+  left: 50%;
+  margin-left: -8px;
+  margin-top: -8px;
+  border: 2px solid transparent;
+  border-top-color: currentcolor;
+  border-radius: 50%;
+  animation: theme-loading-spin 0.6s linear infinite;
+}
+
+@keyframes theme-loading-spin {
+
+  to {
+    transform: rotate(360deg);
+  }
+}