https://github.com/daniguardiola/classy-ink
Build classy CLI interfaces with utility classes and Ink.
https://github.com/daniguardiola/classy-ink
cli ink javascript tailwindcss ui utility-classes
Last synced: 5 months ago
JSON representation
Build classy CLI interfaces with utility classes and Ink.
- Host: GitHub
- URL: https://github.com/daniguardiola/classy-ink
- Owner: DaniGuardiola
- License: mit
- Created: 2023-11-02T23:52:20.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-11-16T19:35:27.000Z (over 1 year ago)
- Last Synced: 2023-11-16T21:02:50.179Z (over 1 year ago)
- Topics: cli, ink, javascript, tailwindcss, ui, utility-classes
- Language: TypeScript
- Homepage:
- Size: 233 KB
- Stars: 32
- Watchers: 1
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
> Build classy CLI interfaces with [Tailwind CSS](https://tailwindcss.com)-inspired utility classes and [Ink](https://term.ink/).
Classy Ink is a simple drop-in replacement for the `Box` and `Text` Ink components. It adds support for utility classes through the `class` prop.
---
Try the demo now!
```
npx classy-ink
```
Or [try it in your browser](https://stackblitz.com/edit/classy-ink-demo?file=README&view=editor).
```
npm install classy-ink
```
```tsx
import { render } from "ink";
import { Box, Text } from "classy-ink";
function Divider() {
return ;
}
function Button({ label }: { label: string }) {
return (
{label}
);
}
function InputField({ label }: { label: string }) {
return (
{label}:
_____________
);
}
function App() {
return (
The Matrix CLI
(Ctrl+C to quit)
Access credentials
);
}
render();
```
You can [run and edit this example live](https://stackblitz.com/edit/classy-ink-example?file=example.tsx&view=editor) in your browser.
- Full support\* for all of `Box` and `Text` style props.
- Optimized for familiarity. Tailwind CSS users will feel right at home.
- Compatible with [Tailwind CSS Intellisense](https://tailwindcss.com/docs/editor-setup#intelli-sense-for-vs-code) and [automatic sorting](https://github.com/tailwindlabs/prettier-plugin-tailwindcss).
- Customizable screen variants (`sm`, `md`, `lg`...) to adapt to different terminal sizes. _(coming soon)_
- Runtime compilation, which enables dynamic values like `border-${color}`.
- Optional cache that prevents recompilation.
_\* While all props are supported, some small subsets of functionality are not fully implemented yet. See the [Current limitations](#current-limitations) section for more information._
- [Install](#install)
- [Example](#example)
- [Features](#features)
- [Contents](#contents)
- [Usage](#usage)
- [IDE features (optional)](#ide-features-optional)
- [Cache (optional)](#cache-optional)
- [Tips](#tips)
- [Utility classes](#utility-classes)
- [`Box` props](#box-props)
- [`Text` props](#text-props)
- [Notes](#notes)
- [Colors](#colors)
- [Borders](#borders)
- [Current limitations](#current-limitations)
- [Custom usage](#custom-usage)
- [Contributing](#contributing)
- [Author](#author)
For a history of changes, see the [changelog](CHANGELOG.md).
1. Import `Box` and `Text` from `classy-ink` instead of `ink`.
```tsx
import { Box, Text } from "classy-ink";
```
2. Use the `class` prop to apply styles.
```tsx
Hello
World!
```
While Classy Ink is completely separate from Tailwind CSS, some tooling is compatible due to the similarities between the two projects. In particular, a big amount of effort was spent on Intellisense compatibility through a hand-made Tailwind CSS configuration.
1. Install the [Tailwind CSS Intellisense extension](https://tailwindcss.com/docs/editor-setup#intelli-sense-for-vs-code) for Visual Studio Code or any supported IDE.
2. Install `tailwindcss` in your project.
```
npm install -D tailwindcss
```
3. Create a `tailwind.config.js` file in the project root with the following content:
```tsx
import { tailwindConfig } from "classy-ink/intellisense";
export default tailwindConfig;
```
For automatic class sorting, set up the [Tailwind CSS Prettier plugin](https://github.com/tailwindlabs/prettier-plugin-tailwindcss).
> Note that the Tailwind CSS configuration is NOT used for the actual compilation or anything else. It's only used for Intellisense.
To use the cache, wrap your app in a ``, for example:
```tsx
import { ClassyInkProvider, Box } from "classy-ink";
function App() {
return (
);
}
```
The cache size can be configured with the `maxCacheSize` prop (default: `500`). It can also be disabled by passing the value `0`.
Note that you might not need the cache at all. CLI apps are usually not very dynamic, so the performance impact of recompiling classes is negligible.
Also, note that the cache uses a [Least Recently Used]() algorithm, in case that's relevant to your use case.
The compilation process occurs at runtime, so you can use dynamic values in your classes. If you're used to Tailwind CSS (where this is not possible), this might be a welcome difference.
For example, the following will work:
```tsx
```
---
You can still pass any style props you want, and they will take precedence over the Classy Ink classes.
For example, in the following code the final value of `flexDirection` will be `"row"` instead of `"column"`:
```tsx
```
---
CLI apps are usually not very dynamic, so the cost of compiling (and recompiling) is often negligible. Furthermore, with the optional cache, it's even less of a problem. This means that normally there's no reason to use style props directly (over utility classes) for performance reasons.
The main exception is a highly dynamic value that changes very frequently. In that case, it's recommended to extract that value into a style prop while leaving others as utility classes.
---
Utilities that support a numeric value (`gap`, `m`, `grow`...) also support the arbitrary value syntax (e.g. `gap-[4]`).
---
Classy Ink is relatively lax about allowed values in comparison to Tailwind CSS. For example, `w-23/58` (equivalent to `width: 0.396551724%`) and `w-71827` will work out of the box, even though they are atypical.
Values like these are not "officially supported" though, and might stop working in a future update. If you need them, use the arbitrary value syntax (e.g. `w-[0.396551%]` or `w-[71827]`) which will always support custom values.
All `` and `` style props are supported. Below are their equivalent Classy Ink utilities.
- `position`: `absolute` and `relative`
- `columnGap`: `gap-x-`
- `rowGap`: `gap-y-`
- `gap`: `gap-`
- `margin`: `m-`
- `margin`: `m--`
- `padding`: `p-`
- `padding`: `p--`
- `flexGrow`: `grow` (value: `1`) and `grow-`
- `flexShrink`: `shrink` (value: `1`) and `shrink-`
- `flexDirection`: `flex-`
- `flexBasis`: `basis-`
- `flexWrap`: `flex-`
- `alignItems`: `items-`
- `alignSelf`: `self-`
- `justifyContent`: `justify-`
- `width`: `w-`, `w-`, `w-[%]` and `w-full`
- `height`: `h-`, `h-`, `h-[%]` and `h-full`
- `minWidth`: `min-w-`, `min-w-`, `min-w-[%]` and `min-w-full`
- `minHeight`: `min-h-`, `min-h-`, `min-h-[%]` and `min-h-full`
- `display`: `flex` and `hidden`
- `borderStyle`: `border-`
- `border<Top|Bottom|Left|Right>Style`: `border-<t|b|l|r>`
- `borderColor`: `border-<color>`
- `border<Top|Bottom|Left|Right>Color`: `border-<t|b|l|r>-<color>`
- `borderDimColor`: `border-dim`
- `border<Top|Bottom|Left|Right>DimColor`: `border-<t|b|l|r>-dim`
- `overflow`: `overflow-<visible|hidden>`
- `overflow<X|Y>`: `overflow-<x|y>-<visible|hidden>`
### <a name='Textprops'></a>`Text` props
- `color`: `text-<color>`
- `backgroundColor`: `bg-<color>`
- `dimColor`: `text-dim`
- `bold`: `font-bold`
- `italic`: `italic`
- `underline`: `underline`
- `strikethrough`: `strike`
- `inverse`: `inverse`
- `wrap`: `whitespace-wrap`, `whitespace-nowrap` (equivalent to `truncate`), `truncate` (truncates the end), `truncate-<start|middle>`
## <a name='Notes'></a>Notes
### <a name='Colors'></a>Colors
The following colors are supported:
- `black`
- `white`
- `gray`
- `red`
- `green`
- `yellow`
- `blue`
- `cyan`
- `magenta`
All colors except `gray` also have a "bright" equivalent named `<color>-bright` (e.g. `red-bright`).
### <a name='Borders'></a>Borders
- `border` sets `borderStyle: "single"` and enables all sides (`borderTop`, `borderBottom`, `borderLeft`, `borderRight`).
- When `border-<t|b|l|r>` is set:
- `borderStyle` is set to `"single"` unless another style is already set **for all sides** (`border-<style>`).
- All other sides are disabled (set to `false`) unless enabled elsewhere. In other words, it functions as a "whitelist". Note that `border` always enables all sides.
### <a name='Currentlimitations'></a>Current limitations
- Setting border style by side/corner (`border-<tl|t|tr|r|br|b|bl|l|a>-<style>`) is not supported.
- `basis` only supports basic numeric values.
- Margin utilities only support negative values through arbitrary value syntax (e.g. `ml-[-1]`). Standard syntax (e.g. `-ml-1`) is not supported. Negative percentages are not supported either.
- There is no sense of "RTL" or "LTR" in Ink, so logical utilities like `ms-<n>` (`margin-inline-start`) are not supported.
## Custom usage
If you have some kind of custom use case, you can use the `useClassyInk` hook or the `compileClass` function directly.
Both take a class string and return an object with the corresponding Ink props. The hook wraps the function and adds memoization and caching logic on top.
Unless there's a good reason to do otherwise, the hook is recommended over the function.
```tsx
// note: incomplete example for illustration purposes
import { compileClass } from "classy-ink";
import { Box } from "ink";
function MyCustomBox({ class: className, ...props }) {
return <Box {...useClassyInk(className)} {...props} />;
}
// or
const inkProps = compileClass("border border-red");
<Box {...inkProps} />;
```
## <a name='Contributing'></a>Contributing
Install [`bun`](https://bun.sh/) and install dependencies with `bun i`.
You can run `bun demo:watch` to start the demo and automatically restart on changes.
Contributions are welcome, especially those that add missing features like the ones listed in [Current limitations](#current-limitations).
## <a name='Author'></a>Author
Classy Ink was built by [Dani Guardiola](https://dio.la/).
Classy Ink is NOT affiliated with Tailwind CSS, Tailwind Labs Inc., or the Ink project.