https://github.com/interline-io/catenary
https://github.com/interline-io/catenary
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/interline-io/catenary
- Owner: interline-io
- License: mit
- Created: 2026-04-02T00:16:01.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-06-01T23:12:16.000Z (about 2 months ago)
- Last Synced: 2026-06-01T23:12:17.124Z (about 2 months ago)
- Language: Vue
- Size: 524 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Catenary
A Vue 3 UI controls library built on [Bulma](https://bulma.io/) and [Material Design Icons](https://pictogrammers.com/library/mdi/). Catenary provides 30 general-purpose, domain-agnostic components designed to be reusable across any application.
Published to GitHub Packages as `@interline-io/catenary`.
## Installation
Configure your project to use the GitHub Packages registry for the `@interline-io` scope. Add to your project's `.npmrc`:
```
@interline-io:registry=https://npm.pkg.github.com
```
Then install:
```bash
pnpm add @interline-io/catenary
```
### Peer dependencies
Your project must provide:
- `vue` 3.5+
- `bulma` 1.0+ -- CSS framework (configured and loaded by your app)
- `@mdi/font` 7.4+ -- Material Design Icons (loaded by your app)
`date-fns` 4.x is a direct dependency and installed automatically.
## Usage
### Vue plugin (recommended)
Register all components globally with the `cat-` prefix:
```ts
import { createApp } from 'vue'
import CatenaryPlugin from '@interline-io/catenary'
import '@interline-io/catenary/style.css'
const app = createApp(App)
app.use(CatenaryPlugin)
app.mount('#app')
```
Components are then available everywhere as ``, ``, ``, etc.
### Individual imports
For tree-shaking, import only the components you need:
```ts
import { CatButton, CatInput, CatField } from '@interline-io/catenary'
import '@interline-io/catenary/style.css'
```
### Nuxt
Create a plugin file to register the components:
```ts
// app/plugins/catenary.ts
import CatenaryPlugin from '@interline-io/catenary'
import '@interline-io/catenary/style.css'
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.use(CatenaryPlugin)
})
```
No Nuxt module configuration is needed. The plugin handles global registration of all `cat-*` components.
### Bulma and icon CSS
The `@interline-io/catenary/style.css` export includes the component-scoped styles extracted from the library. It does **not** include the full Bulma stylesheet or Material Design Icons font. You must load those in your app's global styles:
```scss
// In your app's main stylesheet or entry point
@use "bulma/sass" with (
$primary: #9e0e84, // customize as needed
);
@use "@mdi/font/css/materialdesignicons.css";
```
Or via CDN/link tags if you prefer.
## Components
### Form controls
| Component | Tag | Description |
|-----------|-----|-------------|
| CatButton | `` | Button with variants, sizes, loading state, icons |
| CatCheckbox | `` | Checkbox with v-model support |
| CatCheckboxGroup | `` | Multiple checkboxes from an options array |
| CatRadio | `` | Radio button |
| CatSwitch | `` | Toggle switch |
| CatInput | `` | Text input with icons, types, variants |
| CatTextarea | `` | Multi-line text input |
| CatSelect | `` | Select dropdown |
| CatTaginput | `` | Tag-based input with autocomplete and custom options |
| CatDatepicker | `` | Calendar date picker with single/multiple selection |
| CatField | `` | Form field wrapper (labels, horizontal layout, addons, grouping) |
| CatSlider | `` | Range slider |
| CatSliderTick | `` | Tick mark for slider |
### Layout and navigation
| Component | Tag | Description |
|-----------|-----|-------------|
| CatTabs | `` | Tab navigation |
| CatTabItem | `` | Individual tab panel |
| CatDropdown | `` | Dropdown menu |
| CatDropdownItem | `` | Item within a dropdown |
| CatModal | `` | Modal dialog with sizes, fullscreen, footer slots |
| CatCard | `` | Card container with optional expand/collapse |
### Data display
| Component | Tag | Description |
|-----------|-----|-------------|
| CatTable | `` | Data table with sortable columns |
| CatTableColumn | `` | Column definition for table |
| CatPagination | `` | Page navigation |
| CatTag | `` | Badge/label tag |
| CatNotification | `` | Notification banner |
| CatMsg | `` | Message box with icon, expand/collapse, close |
### Utilities
| Component | Tag | Description |
|-----------|-----|-------------|
| CatIcon | `` | Material Design Icon wrapper |
| CatLoading | `` | Loading spinner overlay |
| CatTooltip | `` | Tooltip overlay |
| CatSearchBar | `` | Search input with clear button |
| CatThemeToggle | `` | Light/dark theme switcher |
## Variants and sizes
Most components accept `variant` and `size` props. The core set is:
```
Variants: primary, link, info, success, warning, danger
Sizes: small, normal, medium, large
```
Some components extend these (e.g., buttons add `white`, `light`, `dark`, `text`, `ghost`). All variant and size constants are exported as TypeScript types and runtime arrays:
```ts
import { CoreVariants, ButtonVariants, type ButtonVariant } from '@interline-io/catenary'
```
## CSS conventions
Components follow a consistent class naming pattern:
- Root element gets both the Bulma class and a `cat-` prefixed class: `class="card cat-card"`
- Bulma helper classes are used directly for spacing, typography, and flexbox
- Custom classes invented by the library always use the `cat-` prefix
- Variant styles use SCSS `@each` loops over Bulma CSS variables
## Development
Requires **Node v22.21.1** (see `.nvmrc`) and **pnpm**.
```bash
pnpm install
pnpm dev # Start Nuxt playground at localhost:3000
pnpm build # Build library (dist/catenary.js + types)
pnpm test # Run tests (vitest + jsdom)
pnpm lint # ESLint (incl. eslint-plugin-vuejs-accessibility)
pnpm typecheck # vue-tsc + nuxi typecheck
pnpm check # Lint + typecheck (runs both in sequence)
pnpm changeset # Record a user-facing change for the next release
```
The `playground/` directory is a Nuxt app with interactive demos for every component. It is a devDependency and is not included in the published package.
## Publishing
Releases are managed with [Changesets](https://github.com/changesets/changesets). PRs that ship a user-facing change should include a changeset file (run `pnpm changeset` and commit the generated `.changeset/*.md`). On merge to `main`, the `Release` workflow opens or updates a "Version Packages" PR that bumps the version and updates `CHANGELOG.md`; merging that PR publishes a new release to GitHub Packages under the `latest` dist-tag.
Pushes to non-`main` branches also publish preview tarballs to GitHub Packages as `0.1.0-branch..`, under the branch name as a dist-tag. These are useful for testing changes in consuming apps before they are released.
