@lanrenbang/basecoat-ultra 0.1.2

package/CHANGELOG-cn.md

@@ -0,0 +1,54 @@
+# Basecoat Ultra 更新日志 (Changelog)
+
+[English](./CHANGELOG.md) | **中文**
+
+本文档记录了 `basecoat-ultra` 相对于上游 Basecoat 的所有主要变更。
+
+## 🚀 核心架构与构建 (Architecture & Build)
+
+*   **模块化重构**: 将原版单体 `basecoat.css` 拆分为 `src/css/parts/` 下的独立模块，便于维护和按需引用。
+*   **Tailwind v4 适配**: 修复了在 CSS 中使用复杂 `@apply` 选择器（如 `[&_svg:not(...)]`）时的转义与语法错误，改用原生 CSS 嵌套写法。
+*   **依赖精简**: 移除了 Nunjucks/Jinja 模板支持，专注于 HTML/JS 组件实现。
+
+## ✨ 组件改进 (Component Improvements)
+
+### 核心组件修复
+*   **Button**:
+    *   修复 Ghost/Link 变体在某些上下文中的背景残留问题。
+    *   增强 Outline 变体的文字对比度。
+*   **Dialog**:
+    *   重构动画曲线，引入 `cubic-bezier` 回弹效果。
+    *   优化居中定位逻辑。
+*   **Dropdown Menu**:
+    *   修复初始化时的可见性闪烁问题（确保初始 `aria-hidden="true"`）。
+    *   支持更灵活的 DOM 结构（直接在 popover 内容上定义 `role="menu"`）。
+*   **Sidebar**:
+    *   优化 `aria-current` 自动高亮逻辑，自动忽略 `href="#"` 空链接。
+*   **Form Elements**:
+    *   修复 Checkbox/Radio/Switch/Sidebar 中 `content` 属性转义符丢失导致的构建错误。
+    *   调整 Select 和 Checkbox 图标颜色 (`oklch`) 以提升对比度。
+    *   Range 滑块增加 hover 阴影与手型光标。
+
+### 新增自定义组件 (New Components)
+*   **Accordion**: 上游仅做文档演示，本项目已将其标准化封装为正式组件。基于 `<details>`/`<summary>` 的纯 CSS 动画手风琴。
+*   **Sheet**: 侧边抽屉组件，支持从屏幕边缘滑出。
+*   **Carousel**: 基础轮播图组件。
+*   **Input OTP**: 验证码/一次性密码输入组件。
+*   **Toggle / Toggle Group**: 独立的开关与开关组组件。
+
+### 外部集成 (External Integrations)
+*   **Date Picker**: 集成 `flatpickr`，并提供深度定制的主题样式。
+*   **Resizable**: 集成 `split.js`，提供可拖拽布局支持。
+
+## 🎨 视觉与主题 (Visuals & Theming)
+
+*   **Catppuccin 主题**: 
+    *   完整集成 Latte, Frappé, Macchiato, Mocha 四款主题。
+    *   提供配套的 `Theme Switcher` 逻辑 (`src/js/catppuccin-theme-switcher.js`)。
+*   **Neumorphism 扩展**:
+    *   新增 `lighting.js`: 实现基于鼠标位置的全局拟态光照效果（灵感来源于 `puikinsh/login-forms`）。
+    *   支持 CSS 3D Transform 翻转效果。
+
+---
+
+*注意：以上变更基于与 Basecoat 原版 (`references/basecoat`) 的对比。*

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Basecoat Ultra Changelog
+
+**English** | [中文](./CHANGELOG-cn.md)
+
+This document records all major changes in `basecoat-ultra` relative to the upstream Basecoat.
+
+## 🚀 Architecture & Build
+
+*   **Modular Refactoring**: Split the monolithic `basecoat.css` into independent modules under `src/css/parts/` for easier maintenance and on-demand usage.
+*   **Tailwind v4 Adaptation**: Fixed escaping and syntax errors when using complex `@apply` selectors (e.g., `[&_svg:not(...)]`) in CSS, replacing them with native CSS nesting syntax.
+*   **Dependency Slimming**: Removed Nunjucks/Jinja template support to focus on HTML/JS component implementation.
+
+## ✨ Component Improvements
+
+### Core Fixes
+*   **Button**:
+    *   Fixed background residue issues for Ghost/Link variants in specific contexts.
+    *   Enhanced text contrast for Outline variants.
+*   **Dialog**:
+    *   Refactored animation curves, introducing `cubic-bezier` bounce effects.
+    *   Optimized centering logic.
+*   **Dropdown Menu**:
+    *   Fixed visibility flicker on initialization (ensured initial `aria-hidden="true"`).
+    *   Supported more flexible DOM structures (defining `role="menu"` directly on popover content).
+*   **Sidebar**:
+    *   Optimized `aria-current` auto-highlighting logic to ignore `href="#"` empty links.
+*   **Form Elements**:
+    *   Fixed build errors caused by missing escape characters in `content` properties for Checkbox/Radio/Switch/Sidebar.
+    *   Adjusted Select and Checkbox icon colors (`oklch`) to improve contrast.
+    *   Added hover shadows and pointer cursor to Range sliders.
+
+### New Custom Components
+*   **Accordion**: Standardized and internalized (upstream only had it as a demo). Pure CSS animation based on `<details>`/`<summary>`.
+*   **Sheet**: Side drawer component supporting slide-in from screen edges.
+*   **Carousel**: Basic carousel component.
+*   **Input OTP**: Verification code/One-Time Password input component.
+*   **Toggle / Toggle Group**: Independent toggle and toggle group components.
+
+### External Integrations
+*   **Date Picker**: Integrated `flatpickr` with deeply customized theme styles.
+*   **Resizable**: Integrated `split.js` providing draggable layout support.
+
+## 🎨 Visuals & Theming
+
+*   **Catppuccin Themes**:
+    *   Fully integrated Latte, Frappé, Macchiato, and Mocha themes.
+    *   Provided matching `Theme Switcher` logic (`src/js/catppuccin-theme-switcher.js`).
+*   **Neumorphism Extension**:
+    *   Added `lighting.js`: Implements global neumorphic lighting effects based on mouse position (Inspired by `puikinsh/login-forms`).
+    *   Supported CSS 3D Transform flip effects.
+
+---
+
+*Note: The above changes are based on comparison with the original Basecoat (`references/basecoat`).*

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 L.R.B
+
+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-cn.md

@@ -0,0 +1,186 @@
+# Basecoat Ultra
+
+[English](./README.md) | **中文**
+
+Basecoat is a set of components built with Tailwind CSS. It is designed to be used with any traditional web stack.
+Basecoat brings the magic of shadcn/ui to any traditional web stack: no React required.
+
+**Basecoat Ultra** 是基于 [Basecoat](https://basecoatui.com) 开发的增强版 UI 库。它保留了原版“Tailwind 优先、框架无关”的核心理念，并在此基础上根据现代审美与轻量化需求进行了深度定制。我们移除了对 Nunjucks/Jinja 的原生支持，转而专注于提供更丰富的交互组件、开箱即用的主题系统以及细腻的视觉增强。
+
+## ✨ 特性 (Features)
+
+### 🛠️ 核心增强与修复 (Core Improvements)
+我们对 Basecoat 原版核心进行了大量细节打磨与 bug 修复（详见 CHANGELOG），包括但不限于：
+- **CSS 模块化**: 将单体 CSS 重构为模块化结构，支持按需加载。
+- **构建修复**: 修复了 Tailwind v4 下复杂选择器的转义问题。
+- **组件优化**: 
+    - `Button`: 修复 Ghost/Link 变体在特定背景下的显示问题。
+    - `Dialog`: 引入更自然的缩放与回弹动画。
+    - `Dropdown Menu`: 修复初始化时的闪烁问题。
+    - `Sidebar`: 智能识别当前页高亮逻辑。
+
+### 🧩 新增组件 (New Components)
+引入了一系列对标 shadcn/ui 的高频组件，且完全不依赖 React/Vue：
+- **Accordion (手风琴)**: 上游仅在文档中作为演示存在，本项目将其逻辑标准化并内置，基于原生 `<details>` 实现，零 JS 依赖动画。
+- **Sheet (侧边抽屉)**: 优雅的侧边滑出面板。
+- **Carousel (轮播图)**: 轻量级轮播组件。
+- **Input OTP (验证码输入)**: 专用的验证码输入框。
+- **Toggle Group (开关组)**: 类似于 Radio Group 的按钮式交互。
+- **Toggle (开关)**: 独立的开关按钮样式。
+
+### 🔌 外部集成 (External Integrations)
+集成了优秀的第三方库以弥补纯 CSS/Vanilla JS 的短板（需单独引入）：
+- **Date Picker**: 基于 [Flatpickr](https://flatpickr.js.org/) 的深度定制，完美适配主题。
+- **Resizable**: 基于 [Split.js](https://split.js.org/) 的可拖拽分割面板。
+
+### 🎨 视觉增强 (Visual Enhancements)
+- **Catppuccin 主题**: 内置 [Catppuccin](https://github.com/catppuccin/catppuccin) 全系列（Latte, Frappé, Macchiato, Mocha）主题支持。
+- **Neumorphism Extension**: 
+    - **全局光照系统**: 独特的鼠标跟随光影效果 (`lighting.js`)，为 `.neu-panel`, `.neu-btn` 等元素赋予拟态光感。
+    - **3D 翻转**: 支持基于 CSS 3D Transform 的卡片翻转效果。
+
+## 📦 安装 (Installation)
+
+本项目已发布到 [JSR (JavaScript Registry)](https://jsr.io/)。
+
+### 1. 安装依赖
+
+```bash
+# 使用 npm
+npx jsr add @lanrenbang/basecoat-ultra
+
+# 使用 bun
+bunx jsr add @lanrenbang/basecoat-ultra
+
+# 使用 deno
+deno add @lanrenbang/basecoat-ultra
+```
+
+### 2. 引入样式
+
+在你的 CSS 文件中（需配置 Tailwind CSS v4）：
+
+```css
+@import "tailwindcss";
+/* 引入核心样式 */
+@import "@lanrenbang/basecoat-ultra/css/basecoat.css"; 
+/* 或者使用 CDN 版本（包含 Tailwind 工具类） */
+/* @import "@lanrenbang/basecoat-ultra/css/basecoat.cdn.css"; */
+
+/* 引入 Catppuccin 主题（可选） */
+@import "@lanrenbang/basecoat-ultra/dist/theme/catppuccin/index.css";
+```
+
+### 3. 引入交互逻辑
+
+你可以全量引入，也可以按需引入：
+
+```javascript
+// 全量引入 (包含所有组件逻辑)
+import '@lanrenbang/basecoat-ultra';
+
+// 或者按需引入
+import '@lanrenbang/basecoat-ultra/basecoat'; // 核心
+import '@lanrenbang/basecoat-ultra/tabs';
+import '@lanrenbang/basecoat-ultra/sheet';
+// ...
+```
+
+对于外部组件（Datepicker, Resizable），需要单独引入：
+
+```javascript
+// Datepicker
+import 'flatpickr/dist/flatpickr.css';
+import '@lanrenbang/basecoat-ultra/css/datepicker.css';
+import '@lanrenbang/basecoat-ultra/datepicker';
+
+// Resizable
+import '@lanrenbang/basecoat-ultra/css/resizable.css';
+import '@lanrenbang/basecoat-ultra/resizable';
+```
+
+对于外部组件（Datepicker, Resizable），需要单独引入：
+
+```javascript
+// Datepicker
+import 'flatpickr/dist/flatpickr.css';
+import '@basecoat/ultra/datepicker-css';
+import '@basecoat/ultra/datepicker';
+
+// Resizable
+import '@basecoat/ultra/resizable-css';
+import '@basecoat/ultra/resizable';
+```
+
+## 🛠️ 开发与贡献 (Development)
+
+本项目使用 [Bun](https://bun.sh) 作为包管理器和运行时，使用 [Vite](https://vitejs.dev) 进行构建。
+
+### 环境搭建
+
+```bash
+# 1. 克隆项目
+git clone https://github.com/your-username/basecoat-ultra.git
+cd basecoat-ultra
+
+# 2. 安装依赖
+bun install
+
+# 3. 启动开发服务器
+bun run dev
+```
+
+### 主题防闪烁 (Anti-flash Script)
+
+为了在使用 Catppuccin 主题切换器时防止页面刷新出现闪烁（FOUC），请将以下脚本放在 HTML 的 `<head>` 标签顶部：
+
+```html
+<script>
+(function() {
+  try {
+    const t = localStorage.getItem('catppuccin-theme');
+    const a = localStorage.getItem('catppuccin-accent');
+    const m = localStorage.getItem('basecoat-mode');
+    const r = document.documentElement;
+    // 优先加载主题配置
+    if (t && a) {
+      r.classList.add(`theme-${t}`, `accent-${a}`);
+      if(['frappe','macchiato','mocha'].includes(t)) r.classList.add('dark');
+    } else if (m) {
+      // 只有明暗模式偏好
+      r.classList.toggle('dark', m === 'dark');
+    } else {
+      // 跟随系统
+      r.classList.toggle('dark', window.matchMedia('(prefers-color-scheme: dark)').matches);
+    }
+  } catch(e) {}
+})();
+</script>
+```
+
+### 发布到 JSR
+
+如果你是维护者，按照以下步骤发布新版本：
+
+1.  登录 JSR (仅需一次):
+    ```bash
+    bunx jsr login
+    ```
+2.  发布:
+    ```bash
+    bunx jsr publish
+    ```
+
+## ❤️ 鸣谢 (Credits)
+
+本项目站在巨人的肩膀上：
+
+*   **[Basecoat](https://basecoatui.com)**: 原创者 [hunvreus](https://github.com/hunvreus)。本项目的大部分基础代码归原作者所有。
+*   **[Catppuccin](https://github.com/catppuccin/palette)**: 提供了美妙的配色方案。
+*   **[puikinsh/login-forms](https://github.com/puikinsh/login-forms/tree/main/forms/neumorphism)**: Neumorphism 光照与 3D 效果的灵感来源。
+*   **[Flatpickr](https://flatpickr.js.org/)** & **[Split.js](https://split.js.org/)**: 优秀的第三方库支持。
+
+## 📄 许可 (License)
+
+本项目遵循 [MIT License](LICENSE.md)。
+Basecoat 原始内容版权归属于 hunvreus。

package/README.md

@@ -0,0 +1,173 @@
+# Basecoat Ultra
+
+**English** | [中文](./README-cn.md)
+
+Basecoat is a set of components built with Tailwind CSS. It is designed to be used with any traditional web stack.
+Basecoat brings the magic of shadcn/ui to any traditional web stack: no React required.
+
+**Basecoat Ultra** is an enhanced UI library based on [Basecoat](https://basecoatui.com). It retains the core philosophy of "Tailwind-first, framework-agnostic" while offering deep customizations tailored for modern aesthetics and lightweight requirements. We have removed native support for Nunjucks/Jinja to focus on providing richer interactive components, an out-of-the-box theming system, and refined visual enhancements.
+
+## ✨ Features
+
+### 🛠️ Core Improvements
+We have polished the Basecoat core with numerous details and bug fixes (see CHANGELOG), including but not limited to:
+- **CSS Modularization**: Refactored monolithic CSS into a modular structure supporting on-demand loading.
+- **Build Fixes**: Resolved escaping issues with complex selectors in Tailwind v4.
+- **Component Optimizations**:
+    - `Button`: Fixed Ghost/Link variant background issues in specific contexts.
+    - `Dialog`: Introduced more natural scaling and bounce animations.
+    - `Dropdown Menu`: Fixed flickering issues during initialization.
+    - `Sidebar`: Intelligent logic for identifying and highlighting the current page.
+
+### 🧩 New Components
+Introduced a series of high-frequency components inspired by shadcn/ui, completely independent of React/Vue:
+- **Accordion**: Originally only a demo in upstream docs; standardized and internalized here. Based on native `<details>`, zero-JS animation.
+- **Sheet**: Elegant side-sliding panel.
+- **Carousel**: Lightweight carousel component.
+- **Input OTP**: Dedicated one-time password input.
+- **Toggle Group**: Button-style interaction similar to Radio Group.
+- **Toggle**: Independent toggle button style.
+
+### 🔌 External Integrations
+Integrated excellent third-party libraries to bridge gaps in pure CSS/Vanilla JS (must be imported separately):
+- **Date Picker**: Deeply customized version based on [Flatpickr](https://flatpickr.js.org/), perfectly adapted to themes.
+- **Resizable**: Draggable split panel based on [Split.js](https://split.js.org/).
+
+### 🎨 Visual Enhancements
+- **Catppuccin Themes**: Built-in support for the full [Catppuccin](https://github.com/catppuccin/catppuccin) suite (Latte, Frappé, Macchiato, Mocha).
+- **Neumorphism Extension**:
+    - **Global Lighting System**: Unique mouse-following lighting effects (`lighting.js`), giving neumorphic feel to `.neu-panel`, `.neu-btn` elements.
+    - **3D Flip**: Supports CSS 3D Transform-based card flip effects.
+
+## 📦 Installation
+
+This project is published to the [JSR (JavaScript Registry)](https://jsr.io/).
+
+### 1. Install Dependencies
+
+```bash
+# Using npm
+npx jsr add @lanrenbang/basecoat-ultra
+
+# Using bun
+bunx jsr add @lanrenbang/basecoat-ultra
+
+# Using deno
+deno add @lanrenbang/basecoat-ultra
+```
+
+### 2. Import Styles
+
+In your CSS file (Tailwind CSS v4 configuration required):
+
+```css
+@import "tailwindcss";
+/* Import core styles */
+@import "@lanrenbang/basecoat-ultra/css/basecoat.css"; 
+/* Or use the CDN version (includes Tailwind utilities) */
+/* @import "@lanrenbang/basecoat-ultra/css/basecoat.cdn.css"; */
+
+/* Import Catppuccin Theme (Optional) */
+@import "@lanrenbang/basecoat-ultra/dist/theme/catppuccin/index.css";
+```
+
+### 3. Import Logic
+
+You can import everything or use on-demand imports:
+
+```javascript
+// Import all component logic
+import '@lanrenbang/basecoat-ultra';
+
+// Or on-demand import
+import '@lanrenbang/basecoat-ultra/basecoat'; // Core
+import '@lanrenbang/basecoat-ultra/tabs';
+import '@lanrenbang/basecoat-ultra/sheet';
+// ...
+```
+
+For external components (Datepicker, Resizable), import them separately:
+
+```javascript
+// Datepicker
+import 'flatpickr/dist/flatpickr.css';
+import '@lanrenbang/basecoat-ultra/css/datepicker.css';
+import '@lanrenbang/basecoat-ultra/datepicker';
+
+// Resizable
+import '@lanrenbang/basecoat-ultra/css/resizable.css';
+import '@lanrenbang/basecoat-ultra/resizable';
+```
+
+## 🛠️ Development
+
+This project uses [Bun](https://bun.sh) as the package manager and runtime, and [Vite](https://vitejs.dev) for building.
+
+### Setup
+
+```bash
+# 1. Clone project
+git clone https://github.com/your-username/basecoat-ultra.git
+cd basecoat-ultra
+
+# 2. Install dependencies
+bun install
+
+# 3. Start dev server
+bun run dev
+```
+
+### Anti-flash Script
+
+To prevent page flicker (FOUC) when using the Catppuccin Theme Switcher on refresh, place the following script at the top of your HTML `<head>` tag:
+
+```html
+<script>
+(function() {
+  try {
+    const t = localStorage.getItem('catppuccin-theme');
+    const a = localStorage.getItem('catppuccin-accent');
+    const m = localStorage.getItem('basecoat-mode');
+    const r = document.documentElement;
+    // Prioritize theme config
+    if (t && a) {
+      r.classList.add(`theme-${t}`, `accent-${a}`);
+      if(['frappe','macchiato','mocha'].includes(t)) r.classList.add('dark');
+    } else if (m) {
+      // Only dark/light mode preference
+      r.classList.toggle('dark', m === 'dark');
+    } else {
+      // Follow system
+      r.classList.toggle('dark', window.matchMedia('(prefers-color-scheme: dark)').matches);
+    }
+  } catch(e) {}
+})();
+</script>
+```
+
+### Publishing to JSR
+
+If you are a maintainer, follow these steps to publish a new version:
+
+1.  Login to JSR (Once):
+    ```bash
+    bunx jsr login
+    ```
+2.  Publish:
+    ```bash
+    bunx jsr publish
+    ```
+
+## ❤️ Credits
+
+This project stands on the shoulders of giants:
+
+*   **[Basecoat](https://basecoatui.com)**: Original creator [hunvreus](https://github.com/hunvreus). Most foundational code belongs to the original author.
+*   **[Catppuccin](https://github.com/catppuccin/palette)**: Provided the beautiful color palettes.
+*   **[puikinsh/login-forms](https://github.com/puikinsh/login-forms/tree/main/forms/neumorphism)**: Inspiration for Neumorphism lighting and 3D effects.
+*   **[Flatpickr](https://flatpickr.js.org/)** & **[Split.js](https://split.js.org/)**: Excellent third-party library support.
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE.md).
+Original Basecoat content copyright belongs to hunvreus.