hipowered.dev/basecoat
1
0
Fork 0
mirror of https://github.com/hunvreus/basecoat.git synced 2026-11-13 13:48:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

Prepare 1.0.0 release

Browse Source
This commit is contained in:
Ronan Berder
2026-06-27 08:55:48 +08:00
parent 2be9606ce4
commit c81900a58d
52 changed files with 2504 additions and 1124 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/src/components/alert.mdx
+1 -1
View File
@@ -44,7 +44,7 @@ Use `alert` for default styling. Add `data-variant="destructive"` for error stat
```html
<div class="alert"><svg class="lucide lucide-info" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10" /><path d="M12 16v-4" /><path d="M12 8h.01" /></svg>
<h2>Heads up!</h2>
<section>You can add components and dependencies to your app using the cli.</section>
<section>You can add components and dependencies to your app.</section>
<footer>
<button type="button" class="btn" data-variant="outline">Enable</button>
</footer>
docs/src/components/combobox.mdx
+1 -1
View File
@@ -18,7 +18,7 @@
## Usage
<Callout title="Template macros available" icon="code" action={{ label: "Read more", href: "/cli#combobox" }}>
<Callout title="Template macros available" icon="code" action={{ label: "More", href: "/templates#combobox" }}>
This component ships a `combobox()` macro for Jinja and Nunjucks.
</Callout>
docs/src/components/command.mdx
+1 -1
View File
@@ -40,7 +40,7 @@
## Usage
<Callout title="Template macros available" icon="code" action={{ label: "Read more", href: "/cli#command" }}>
<Callout title="Template macros available" icon="code" action={{ label: "More", href: "/templates#command" }}>
This component ships `command()` and `command_dialog()` macros for Jinja and Nunjucks.
</Callout>
docs/src/components/dialog.mdx
+1 -1
View File
@@ -31,7 +31,7 @@
## Usage
<Callout title="Template macros available" icon="code" action={{ label: "Read more", href: "/cli#dialog" }}>
<Callout title="Template macros available" icon="code" action={{ label: "More", href: "/templates#dialog" }}>
This component ships a `dialog()` macro for Jinja and Nunjucks.
</Callout>
docs/src/components/dropdown-menu.mdx
+1 -1
View File
@@ -48,7 +48,7 @@
## Usage
<Callout title="Template macros available" icon="code" action={{ label: "Read more", href: "/cli#dropdown_menu" }}>
<Callout title="Template macros available" icon="code" action={{ label: "More", href: "/templates#dropdown_menu" }}>
This component ships a `dropdown_menu()` macro for Jinja and Nunjucks.
</Callout>
docs/src/components/popover.mdx
+1 -1
View File
@@ -32,7 +32,7 @@
## Usage
<Callout title="Template macros available" icon="code" action={{ label: "Read more", href: "/cli#popover" }}>
<Callout title="Template macros available" icon="code" action={{ label: "More", href: "/templates#popover" }}>
This component ships a `popover()` macro for Jinja and Nunjucks.
</Callout>
docs/src/components/scroll-area.mdx
+2 -2
View File
@@ -45,7 +45,7 @@ Or import only the base CSS and one style pack.
@import "basecoat-css/styles/vega.css";
```
Scroll Area uses Basecoat base scrollbar utilities and has no dedicated component CSS file.
Scroll Area uses Basecoat scrollbar component classes.
Using CDN or bundler imports? See the [Installation page](/installation).
@@ -65,7 +65,7 @@ Use `scrollbar` or `scrollbar-sm` on an element that already scrolls with `overf
Use `scrollbar` or `scrollbar-sm` on an element that already scrolls with `overflow-auto`, `overflow-y-auto`, or `overflow-x-auto`.
The utility augments native scrolling for cross-browser styling. It does not wrap content, replace browser scroll behavior, or require JavaScript.
The component class augments native scrolling for cross-browser styling. It does not wrap content, replace browser scroll behavior, or require JavaScript.
## Examples
docs/src/components/select.mdx
+1 -1
View File
@@ -24,7 +24,7 @@
## Usage
<Callout title="Template macros available" icon="code" action={{ label: "Read more", href: "/cli#select" }}>
<Callout title="Template macros available" icon="code" action={{ label: "More", href: "/templates#select" }}>
This component ships a `select()` macro for Jinja and Nunjucks.
</Callout>
docs/src/components/sidebar.mdx
+1 -1
View File
@@ -2,7 +2,7 @@
## Usage
<Callout title="Template macros available" icon="code" action={{ label: "Read more", href: "/cli#sidebar" }}>
<Callout title="Template macros available" icon="code" action={{ label: "More", href: "/templates#sidebar" }}>
This component ships a `sidebar()` macro for Jinja and Nunjucks.
</Callout>
docs/src/components/tabs.mdx
+1 -1
View File
@@ -57,7 +57,7 @@
## Usage
<Callout title="Template macros available" icon="code" action={{ label: "Read more", href: "/cli#tabs" }}>
<Callout title="Template macros available" icon="code" action={{ label: "More", href: "/templates#tabs" }}>
This component ships a `tabs()` macro for Jinja and Nunjucks.
</Callout>
docs/src/components/toast.mdx
+1 -1
View File
@@ -29,7 +29,7 @@
## Usage
<Callout title="Template macros available" icon="code" action={{ label: "Read more", href: "/cli#toast" }}>
<Callout title="Template macros available" icon="code" action={{ label: "More", href: "/templates#toast" }}>
This component ships `toaster()` and `toast()` macros for Jinja and Nunjucks.
</Callout>
docs/src/customization.mdx
+11 -4
View File
@@ -53,7 +53,7 @@ Install the fonts with Fontsource:
npm install @fontsource/geist-sans @fontsource/geist-mono
```
Then import the font files and override the font tokens after Basecoat:
Then import the font files. Basecoat's default font tokens already reference Geist with full system fallbacks:
```css
@import "tailwindcss";
@@ -66,10 +66,17 @@ Then import the font files and override the font tokens after Basecoat:
@import "@fontsource/geist-mono/500.css";
@import "@fontsource/geist-mono/600.css";
@import "@fontsource/geist-mono/700.css";
```
If you use different fonts, override the font tokens after Basecoat:
```css
@import "tailwindcss";
@import "basecoat-css/sera";
:root {
--font-sans: "Geist Sans", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
--font-heading: "Geist Sans", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
--font-mono: "Geist Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
--font-sans: "Inter", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
--font-heading: "Inter", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
--font-mono: "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
}
```
docs/src/docs.json
+3 -3
View File
@@ -24,9 +24,9 @@
},
{
"type": "item",
"label": "CLI",
"slug": "cli",
"icon": "square-terminal"
"label": "Templates",
"slug": "templates",
"icon": "code"
},
{
"type": "item",
docs/src/installation.mdx
+45 -16
View File
@@ -1,3 +1,7 @@
import packageJson from "../../packages/css/package.json"
export const basecoatVersion = packageJson.version
# Installation
Basecoat can be used from a CDN or installed with npm. Use the CDN for simple static pages and prototypes. Use npm when your project already has a Tailwind CSS build step.
@@ -9,32 +13,27 @@ Basecoat can be used from a CDN or installed with npm. Use the CDN for simple st
Use the default bundled stylesheet. It is an alias for the Vega style bundle.
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.0-beta.7/dist/basecoat.cdn.min.css" />
```
<Code lang="html" code={`<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/basecoat-css@${basecoatVersion}/dist/basecoat.cdn.min.css" />`} />
You can also use one of the named style bundles: `vega`, `nova`, `maia`, `lyra`, `mira`, `luma`, `sera`, or `rhea`.
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.0-beta.7/dist/basecoat-maia.cdn.min.css" />
```
<Code lang="html" code={`<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/basecoat-css@${basecoatVersion}/dist/basecoat-maia.cdn.min.css" />`} />
</Step>
<Step title="Add JavaScript when needed">
Most components are CSS-only. Interactive components need JavaScript. Use the all-in-one bundle when file size is not a concern.
```html
<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.0-beta.7/dist/js/all.min.js" defer></script>
```
<Code lang="html" code={`<script src="https://cdn.jsdelivr.net/npm/basecoat-css@${basecoatVersion}/dist/js/all.min.js" defer></script>`} />
Or load the Basecoat runtime once, then only the component scripts you use.
```html
<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.0-beta.7/dist/js/basecoat.min.js" defer></script>
<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.0-beta.7/dist/js/dropdown-menu.min.js" defer></script>
<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.0-beta.7/dist/js/select.min.js" defer></script>
```
<Code
lang="html"
code={`<script src="https://cdn.jsdelivr.net/npm/basecoat-css@${basecoatVersion}/dist/js/basecoat.min.js" defer></script>
<script src="https://cdn.jsdelivr.net/npm/basecoat-css@${basecoatVersion}/dist/js/dropdown-menu.min.js" defer></script>
<script src="https://cdn.jsdelivr.net/npm/basecoat-css@${basecoatVersion}/dist/js/select.min.js" defer></script>`}
/>
</Step>
<Step title="Use the markup">
@@ -65,7 +64,7 @@ Or load the Basecoat runtime once, then only the component scripts you use.
| `dist/basecoat-{style}.cdn.min.css` | Standalone CDN stylesheet for `vega`, `nova`, `maia`, `lyra`, `mira`, `luma`, `sera`, or `rhea`. |
| `dist/basecoat-base.cdn.min.css` | Base tokens, utilities, and component structure without a style pack. |
| `dist/basecoat-compat.cdn.min.css` | Optional pre-1.0 compatibility aliases. Load after Basecoat. |
| `dist/js/all.min.js` | All JavaScript components. |
| `dist/js/all.min.js` | All auto-initialized JavaScript components except Chart. |
| `dist/js/basecoat.min.js` | Runtime only. Load once before individual component scripts. |
| `dist/js/{component}.min.js` | Individual JavaScript component file. |
@@ -168,6 +167,24 @@ import "basecoat-css/select";
</Step>
</Steps>
### Templates
Basecoat ships optional Nunjucks and Jinja templates with `basecoat-css`.
If you previously used `basecoat-cli`, install `basecoat-css` instead and copy the template files from the package.
<CodeGroup>
```bash title="Nunjucks"
cp -R node_modules/basecoat-css/templates/nunjucks ./templates/basecoat
```
```bash title="Jinja"
cp -R node_modules/basecoat-css/templates/jinja ./templates/basecoat
```
</CodeGroup>
See [Templates](/templates) for the available macros and arguments.
### CSS imports
| Import | Description |
@@ -181,14 +198,23 @@ import "basecoat-css/select";
| `basecoat-css/all.css` | Full default stylesheet plus all style-pack CSS. Use only when you need every style pack available at runtime. |
| `basecoat-css/compat` | Optional pre-1.0 compatibility aliases. Load after Basecoat. |
### Template files
| Path | Description |
| --- | --- |
| `node_modules/basecoat-css/templates/nunjucks` | Nunjucks templates. |
| `node_modules/basecoat-css/templates/jinja` | Jinja templates. |
### JavaScript imports
| Import | Description |
| --- | --- |
| `basecoat-css/all` | All JavaScript components. |
| `basecoat-css/all` | All auto-initialized JavaScript components except Chart. |
| `basecoat-css/basecoat` | Runtime only. Import once before individual component scripts. |
| `basecoat-css/chart` | Chart helper. Load Chart.js separately. |
| `basecoat-css/combobox` | Combobox controller. |
| `basecoat-css/command` | Command controller. |
| `basecoat-css/drawer` | Drawer controller. |
| `basecoat-css/dropdown-menu` | Dropdown Menu controller. |
| `basecoat-css/popover` | Popover controller. |
| `basecoat-css/range` | Slider/range controller. |
@@ -201,6 +227,7 @@ import "basecoat-css/select";
These components need JavaScript for behavior:
- [Accordion](/components/accordion)
- [Combobox](/components/combobox)
- [Command](/components/command)
- [Drawer](/components/drawer)
@@ -212,6 +239,8 @@ These components need JavaScript for behavior:
- [Tabs](/components/tabs)
- [Toast](/components/toast)
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.
## Compatibility
docs/src/introduction.md
+2 -2
View File
@@ -6,7 +6,7 @@
Tailwind won. But building UIs with utility classes alone kinda sucks. Most Tailwind libraries like Flowbite, Preline, or even Tailwind UI ask you to copy walls of unreadable classes into your HTML. It works, but it's messy and hard to maintain.
shadcn/ui avoids that by wrapping everything in React components. It also gives you a killer design system, theme support, a CLI, and a growing ecosystem.
shadcn/ui avoids that by wrapping everything in React components. It also gives you a killer design system, theme support, and a growing ecosystem.
But maybe you're not using React. Maybe your app is built with plain HTML. Or Flask. Or Rails. Or Laravel. Or Django. Or whatever.
@@ -28,7 +28,7 @@ Add a single CSS file to your Tailwind setup. Use components by dropping in simp
Some components (like modals or dropdowns) use a tiny bit of vanilla JavaScript. You can skip it if you don't need interactivity.
There's also a CLI to help you scaffold components and get set up fast.
Optional Nunjucks and Jinja templates ship with the package for server-rendered apps.
[Check out the installation guide](/installation) to get started.
docs/src/cli.mdx → docs/src/templates.mdx
+61 -52
View File
@@ -1,61 +1,15 @@
# CLI
# Templates
## Install Components
<Callout title="basecoat-cli is deprecated" icon="triangle-alert">
Template files now ship with `basecoat-css`. If you previously copied templates with `basecoat-cli`, install `basecoat-css` instead and copy the files from `node_modules/basecoat-css/templates`.
</Callout>
Use the CLI to copy Basecoat component assets into your project. It can install CSS, JavaScript, and the matching Nunjucks or Jinja macros for components that ship template helpers.
Basecoat ships optional Nunjucks and Jinja macros for components with larger HTML structures. They generate the same semantic Basecoat markup shown in the component docs, while keeping repeated server-rendered markup easier to maintain.
<CodeGroup>
```bash title="npm"
npx basecoat-cli add dialog
```
```bash title="pnpm"
pnpm dlx basecoat-cli add dialog
```
```bash title="bun"
bunx basecoat-cli add dialog
```
```bash title="yarn"
yarn dlx basecoat-cli add dialog
```
</CodeGroup>
The CLI asks which template engine you use and where it should copy JavaScript and macro files.
The templates are versioned with `basecoat-css`, so the generated markup matches the CSS and JavaScript files you installed.
## Macros
Nunjucks and Jinja macros are optional helpers for components with larger HTML structures. They generate the same semantic Basecoat markup shown in the component docs.
<CodeGroup>
```jinja title="Nunjucks"
{% from "select.njk" import select %}
{{ select(
name="fruit",
items=[
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
{ value: "blueberry", label: "Blueberry" }
]
) }}
```
```jinja title="Jinja"
{% from "select.html.jinja" import select %}
{{ select(
name="fruit",
items=[
{ "value": "apple", "label": "Apple" },
{ "value": "banana", "label": "Banana" },
{ "value": "blueberry", "label": "Blueberry" }
]
) }}
```
</CodeGroup>
### Public Macros
| Component | Macro | Nunjucks | Jinja |
| --- | --- | --- | --- |
| [Combobox](/components/combobox) | `combobox()` | [combobox.njk](https://github.com/hunvreus/basecoat/blob/main/src/nunjucks/combobox.njk#L18) | [combobox.html.jinja](https://github.com/hunvreus/basecoat/blob/main/src/jinja/combobox.html.jinja#L4) |
@@ -72,6 +26,61 @@ Nunjucks and Jinja macros are optional helpers for components with larger HTML s
Some macro files include internal recursive helpers such as `render_select_items()`. Those helpers are implementation details and are not part of the public API.
## Usage
<Steps>
<Step>
### Install Templates
Copy the template folder for your template engine from `basecoat-css`. Templates are meant to be app-owned, so you can edit them after copying.
<CodeGroup>
```bash title="Nunjucks"
cp -R node_modules/basecoat-css/templates/nunjucks ./templates/basecoat
```
```bash title="Jinja"
cp -R node_modules/basecoat-css/templates/jinja ./templates/basecoat
```
</CodeGroup>
Copy only the files you use if you do not want the full template folder.
You can also copy the [Nunjucks templates](https://github.com/hunvreus/basecoat/tree/main/src/nunjucks) or [Jinja templates](https://github.com/hunvreus/basecoat/tree/main/src/jinja) from GitHub.
</Step>
<Step>
### Use a Macro
Import a macro from the copied template file, then call it with the props for that component.
<CodeGroup>
```jinja title="Nunjucks"
{% from "basecoat/select.njk" import select %}
{{ select(
name="fruit",
items=[
{ value: "apple", label: "Apple" },
{ value: "banana", label: "Banana" },
{ value: "blueberry", label: "Blueberry" }
]
) }}
```
```jinja title="Jinja"
{% from "basecoat/select.html.jinja" import select %}
{{ select(
name="fruit",
items=[
{ "value": "apple", "label": "Apple" },
{ "value": "banana", "label": "Banana" },
{ "value": "blueberry", "label": "Blueberry" }
]
) }}
```
</CodeGroup>
</Step>
</Steps>
## Macro Reference
### `combobox()`