@allxsmith/bestax-bulma 5.1.2 → 5.1.3

package/README.md

@@ -4,13 +4,15 @@
 [![npm downloads](https://img.shields.io/npm/dm/@allxsmith/bestax-bulma.svg)](https://www.npmjs.com/package/@allxsmith/bestax-bulma)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/@allxsmith/bestax-bulma.svg)](https://bundlephobia.com/package/@allxsmith/bestax-bulma)
 [![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue.svg)](https://www.typescriptlang.org/)
-[![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen.svg)](https://github.com/allxsmith/bestax)
+[![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen.svg)](https://github.com/allxsmith/bestax/blob/main/bulma-ui/jest.config.js)
 [![Bulma](https://img.shields.io/badge/Bulma-v1.0+-00d1b2.svg)](https://bulma.io)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-React Bulma components library - TypeScript-first component library for Bulma CSS framework. Build accessible, modern UIs with fully-typed React components.
+TypeScript-first React component library for the **Bulma v1** CSS framework — 80+ fully typed, tree-shakeable components, including extras like Carousel, Dialog, Sidebar, Steps, and date/time pickers.
 
-A modern, flexible React component library built with the latest Bulma v1 and TypeScript.
+**Requires React `^18 || ^19`.** Bulma v1 is the only runtime dependency and installs automatically.
+
+Part of the [bestax monorepo](https://github.com/allxsmith/bestax) — see also [`create-bestax`](https://www.npmjs.com/package/create-bestax) for scaffolding new projects.
 
 ---
 
@@ -25,79 +27,91 @@ A modern, flexible React component library built with the latest Bulma v1 and Ty
 
 ## 🚀 Getting Started
 
+Starting fresh? Scaffold a ready-to-go app instead: `npm create bestax@latest my-app`.
+
 ### 1. Install the package
 
 ```bash
 npm install @allxsmith/bestax-bulma
 # or
-yarn add @allxsmith/bestax-bulma
+pnpm add @allxsmith/bestax-bulma
 ```
 
-### 2. Import Bulma CSS
+### 2. Import the CSS
 
-You must include Bulma’s CSS in your project. The easiest way is to import it in your main JS/TS file:
+The library bundles its own CSS (Bulma v1 + the bestax extras). Import it once in your main JS/TS file:
 
 ```js
-import 'bulma/css/bulma.min.css';
+import '@allxsmith/bestax-bulma/bestax.css';
 ```
 
-Or add it via CDN in your HTML:
+Prefer stock Bulma? That works too — add `extras.css` for the bestax-only components' styles:
 
-```html
-<link
-  rel="stylesheet"
-  href="https://cdn.jsdelivr.net/npm/bulma@1.0.4/css/bulma.min.css"
-/>
+```js
+import 'bulma/css/bulma.min.css';
+import '@allxsmith/bestax-bulma/extras.css';
 ```
 
+More flavors are shipped as subpath exports — prefixed classes (`versions/bestax-prefixed.css` + `<ConfigProvider classPrefix="bestax-">`), no-helpers, no-dark-mode, and raw SCSS at `@allxsmith/bestax-bulma/scss/*`. See the [installation guide](https://bestax.io/docs/guides/getting-started/installation).
+
 ### 3. (Optional) Add an Icon Library
 
-Many components work well with icons. We recommend [Font Awesome](https://fontawesome.com/):
+Five icon libraries are supported as optional peer dependencies: [Font Awesome](https://fontawesome.com/) (`@fortawesome/fontawesome-free`), Material Design Icons (`@mdi/font`), `ionicons`, `material-icons`, and `material-symbols`.
 
 ```bash
 npm install @fortawesome/fontawesome-free
 ```
 
-And then import in your code as needed.
+Set the default for your whole app with [`ConfigProvider`](https://bestax.io/docs/api/helpers/config), e.g. `<ConfigProvider iconLibrary="fa">`.
 
 ### 4. Quick Example
 
-Here’s how to use the `Button` component:
-
 ```tsx
-import React from 'react';
+import '@allxsmith/bestax-bulma/bestax.css';
 import { Button } from '@allxsmith/bestax-bulma';
-import 'bulma/css/bulma.min.css';
 
 function App() {
   return (
-    <div>
-      <Button color="primary" onClick={() => alert('Clicked!')}>
-        Click Me
-      </Button>
-    </div>
+    <Button color="primary" onClick={() => alert('Clicked!')}>
+      Click Me
+    </Button>
   );
 }
 
 export default App;
 ```
 
+### 5. Theming and Dark Mode
+
+Wrap your app in [`Theme`](https://bestax.io/docs/api/helpers/theme) to override Bulma's `--bulma-*` CSS variables and control the color scheme:
+
+```tsx
+import { Theme } from '@allxsmith/bestax-bulma';
+
+<Theme isRoot colorMode="system">
+  {/* colorMode: 'light' | 'dark' | 'system' */}
+  <App />
+</Theme>;
+```
+
 ---
 
 ## ⭐ Why Choose bestax-bulma?
 
-- **Ultra-lightweight: Only 21KB gzipped** ✨
-  3-20x smaller than most popular React UI libraries (which range from 60-500KB+ gzipped)
 - **Supports the latest Bulma v1.x**
   Other React Bulma libraries are stuck on Bulma 0.9.4 — bestax-bulma is built for the future.
+- **80+ components**
+  All of Bulma v1, plus extras: Carousel, Dialog, Sidebar, Steps, Autocomplete, Taginput, DateInput/TimeInput/DateTimeInput pickers, and more. (Migrating from v2? Snackbar merged into [Toast](https://bestax.io/docs/api/components/toast).)
+- **Dark mode & theming built in**
+  `Theme colorMode`, `--bulma-*` variable overrides, and prefixed-class builds via `ConfigProvider`.
 - **Just one dependency: Bulma**
-  Every Bulma library depends on it — we ship it automatically. Clean install, smaller bundle, fewer security concerns.
+  Every Bulma library depends on it — we ship it automatically. Clean install, fewer security concerns.
+- **Tree-shakeable ESM + CJS**
+  Import only what you use — see the live [bundle size](https://bundlephobia.com/package/@allxsmith/bestax-bulma).
 - **99% unit test coverage**
-  Rigorously tested for reliability and stability.
+  Enforced in CI by the [jest config](https://github.com/allxsmith/bestax/blob/main/bulma-ui/jest.config.js) — not just claimed.
 - **100% TypeScript**
   Full type safety for you and your team.
-- **100% Bulma Implementation**
-  Complete bulma implementation.
 - **Active developer support**
   Issues? Questions? PRs? Get fast responses and real improvements.
 
@@ -117,7 +131,7 @@ View the package on npmjs:
 👉 [https://bestax.io](https://bestax.io)
 
 > **Always refer to the [documentation site](https://bestax.io) first:**  
-> It’s the most complete and up-to-date source for everything bestax-bulma!
+> It's the most complete and up-to-date source for everything bestax-bulma!
 
 ---
 
@@ -134,13 +148,22 @@ Explore live, interactive component examples in our Storybook:
 Building with an AI agent (Claude Code, Cursor, Copilot)? bestax-bulma ships LLM-optimized docs:
 
 - 📘 **[LLMs guide](https://bestax.io/docs/guides/llms)** — how to use the library with AI tools
-- 📄 **[llms.txt](https://bestax.io/llms.txt)** — curated index · **[llms-full.txt](https://bestax.io/llms-full.txt)** — the full docs in one file
+- 📄 **[llms.txt](https://bestax.io/llms.txt)** — curated index · **[llms-full.txt](https://bestax.io/llms-full.txt)** — the full docs in one file · every docs page is also served as raw markdown
 - 🧩 **[Agent Skills](https://bestax.io/docs/skills/intro)** — teach your agent the bestax way:
 
+  | Skill                     | Use it when…                                                                     |
+  | ------------------------- | -------------------------------------------------------------------------------- |
+  | `bestax-layout-scaffold`  | Turning a high-level request (dashboard, landing page, …) into a responsive page |
+  | `bestax-form`             | Building forms — Field/Control composition and the full input inventory          |
+  | `bestax-theming`          | Customizing colors, fonts, dark mode via `Theme` and `--bulma-*` variables       |
+  | `bestax-custom-component` | Building a new custom component beyond stock Bulma, the bestax way               |
+
   ```bash
   npx skills add https://github.com/allxsmith/bestax --skill bestax-layout-scaffold
   ```
 
+  New projects get the skills automatically with `npm create bestax@latest my-app --skills` (plus a generated `CLAUDE.md`).
+
 ---
 
 ## 🙏 Special Thanks
@@ -151,7 +174,7 @@ bestax-bulma is built on top of the incredible [@jgthms/bulma](https://github.co
 
 If you find Bulma useful, please consider [sponsoring Jeremy Thomas](https://github.com/sponsors/jgthms) to support the continued development of Bulma.
 
-_Note: We are not affiliated with Bulma or Jeremy Thomas in any way...We’re just big fans of the Bulma framework!_
+_Note: We are not affiliated with Bulma or Jeremy Thomas in any way...We're just big fans of the Bulma framework!_
 
 ---
 
@@ -160,7 +183,7 @@ _Note: We are not affiliated with Bulma or Jeremy Thomas in any way...We’re ju
 - The [Bulma CSS framework](https://bulma.io) is © Jeremy Thomas and licensed under the [MIT License](https://github.com/jgthms/bulma/blob/master/LICENSE).
 - Some example content and documentation in this site is adapted from the Bulma website ([CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)), © Jeremy Thomas.
 
-See [Bulma’s license page](https://github.com/jgthms/bulma/blob/main/LICENSE) for more details.
+See [Bulma's license page](https://github.com/jgthms/bulma/blob/main/LICENSE) for more details.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allxsmith/bestax-bulma",
-  "version": "5.1.2",
+  "version": "5.1.3",
   "description": "A fully-typed React component library for the Bulma CSS framework. Build modern UIs quickly with reusable, accessible, and customizable Bulma-based React components.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",

package/src/scss/CLAUDE.md

@@ -0,0 +1,55 @@
+# scss/ — styles for the bestax "extras"
+
+**Only extras get SCSS.** Components that are stock Bulma (Button, Card, Navbar, …) ship no CSS
+of their own — Bulma provides it. A partial exists only for components that extend beyond Bulma
+(Carousel, Collapse, Dialog, the extended form inputs, …) — or that extend a stock component
+(e.g. `_tabs.scss` adds vertical Tabs). The `_index.scss` files are the authoritative inventory.
+
+## Structure
+
+- `bestax.scss` — main entrypoint: `@use 'bulma/sass' with ($primary: #1e6b99)` + all the extras
+- `extras.scss` — extras-only entrypoint (builds `dist/extras.css`, for apps bringing their own Bulma)
+- `components/`, `form/`, `elements/`, `helpers/` — one `_foo.scss` partial per extra,
+  **registered in that folder's `_index.scss`** (an unregistered partial silently ships nothing)
+- `_variables.scss` — `$extras-*` tokens derived from Bulma's HSL channel vars (`--bulma-primary-h/s/l`)
+- `_mixins.scss` — shared mixins: `extras-transition`, `extras-focus-outline` (a11y), `extras-sr-only`
+- `versions/` — the flavor builds: `bestax-prefixed`, `bestax-no-helpers`, `bestax-no-dark-mode`,
+  `bestax-no-helpers-prefixed`. A new partial is included by all of them automatically (they reuse
+  the same `_index` imports), but must **work** under each — especially the prefixed build.
+
+## The pattern (every partial follows it — `components/_collapse.scss` is the template)
+
+```scss
+@use 'bulma/sass/utilities/initial-variables' as iv;
+@use 'bulma/sass/utilities/css-variables' as cv;
+@use '../mixins' as *;
+
+// 1. SCSS vars, !default, derived from Bulma tokens — never hardcoded hex
+$collapse-border-color: cv.getVar('border') !default;
+
+// 2. Register them as --bulma-* CSS vars on the root class
+.#{iv.$class-prefix}collapse {
+  @include cv.register-vars(
+    (
+      'collapse-border-color': #{$collapse-border-color},
+    )
+  );
+}
+
+// 3. Consume only via cv.getVar(); class names only via the prefix interpolation
+.#{iv.$class-prefix}collapse.#{iv.$class-prefix}is-bordered {
+  border: 1px solid cv.getVar('collapse-border-color');
+}
+```
+
+Rules the pattern encodes:
+
+- **Never a literal class selector** (`.collapse`) — always `.#{iv.$class-prefix}collapse`,
+  or the `bestax-prefixed` flavor breaks silently.
+- **Never a raw color/size value** in declarations — derive from Bulma tokens via `cv.getVar()`
+  so the extra is themeable exactly like stock Bulma (`--bulma-collapse-border-color: …`).
+  This is the contract the `Theme` component and the `bestax-theming` skill rely on.
+- **Reuse `extras-*` mixins** for transitions, focus outlines, and screen-reader-only content
+  instead of re-rolling them (focus style consistency is an a11y requirement).
+- New CSS variables should be documented in
+  `skills/bestax-theming/references/css-variables.md` alongside the docs page.