Skip to content

Commit ad3a8d3

Browse files
cray0000cray0000
committed
docs: write up docs
1 parent 690224a commit ad3a8d3

17 files changed

Lines changed: 3362 additions & 43 deletions

‎docs/api/babel.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Babel Configuration
2+
3+
CSSX uses a Babel preset to transform styles at build time.
4+
5+
## cssxjs/babel
6+
7+
The Babel preset that transforms CSSX syntax.
8+
9+
```js
10+
// babel.config.js
11+
module.exports = {
12+
presets: [
13+
['cssxjs/babel', options]
14+
]
15+
}
16+
```
17+
18+
## Options
19+
20+
| Option | Type | Default | Description |
21+
|--------|------|---------|-------------|
22+
| `platform` | `'web'` \| `'ios'` \| `'android'` | `'web'` | Target platform |
23+
| `reactType` | `'react-native'` \| `'web'` | auto | React target type |
24+
| `cache` | `'teamplay'` | auto | Caching library |
25+
| `transformPug` | `boolean` | `true` | Enable Pug transformation |
26+
| `transformCss` | `boolean` | `true` | Enable CSS transformation |
27+
28+
## Example Configuration
29+
30+
```js
31+
// babel.config.js
32+
module.exports = {
33+
presets: [
34+
['cssxjs/babel', {
35+
transformPug: false, // Disable pug if not using it
36+
cache: 'teamplay' // Force teamplay caching
37+
}]
38+
]
39+
}
40+
```
41+
42+
## Platform Detection
43+
44+
The `platform` option is typically set automatically based on your bundler configuration:
45+
46+
- **React Native / Expo**: Set via Metro bundler
47+
- **Web**: Defaults to `'web'`
48+
49+
You can also set platform-specific variables in your Stylus code:
50+
51+
```stylus
52+
.button
53+
padding 16px
54+
55+
if __IOS__
56+
padding-top 20px // Extra padding for iOS safe area
57+
58+
if __ANDROID__
59+
elevation 4 // Android-specific shadow
60+
```
61+
62+
## Caching
63+
64+
When `cache: 'teamplay'` is set (or auto-detected), the Babel transform generates code that integrates with [teamplay](https://github.com/startupjs/teamplay) for optimized style memoization.
65+
66+
See the [Caching guide](/guide/caching) for more details.
67+
68+
## What Gets Transformed
69+
70+
The Babel preset transforms:
71+
72+
1. **`styl` template literals** → Compiled style objects
73+
2. **`css` template literals** → Compiled style objects
74+
3. **`pug` template literals** → JSX elements (if enabled)
75+
4. **`styleName` props** → Connected to compiled styles
76+
5. **`part` props** → Part style injection points
77+
78+
### Before Transform
79+
80+
```jsx
81+
function Button({ children }) {
82+
return (
83+
<button styleName="button">
84+
<span part="icon">★</span>
85+
{children}
86+
</button>
87+
)
88+
89+
styl`
90+
.button
91+
padding 12px 24px
92+
background blue
93+
`
94+
}
95+
```
96+
97+
### After Transform
98+
99+
The Babel preset converts this into optimized runtime code that:
100+
- Compiles Stylus to style objects at build time
101+
- Connects `styleName` to the compiled styles
102+
- Injects part style props automatically
103+
104+
## TypeScript
105+
106+
CSSX works with TypeScript. The `styl` and `pug` template literals are removed at compile time, so no runtime types are needed.
107+
108+
```tsx
109+
import { styl } from 'cssxjs'
110+
111+
interface CardProps {
112+
title: string
113+
children: React.ReactNode
114+
}
115+
116+
function Card({ title, children }: CardProps) {
117+
return (
118+
<div styleName="card">
119+
<h2 styleName="title">{title}</h2>
120+
{children}
121+
</div>
122+
)
123+
124+
styl`
125+
.card
126+
background white
127+
.title
128+
margin 0
129+
`
130+
}
131+
```
132+
133+
For `styleName` prop typing, you may need to extend JSX types in your project.

‎docs/api/cssx.md‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎docs/api/index.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# API Reference
2+
3+
This section documents all exports from the `cssxjs` package.
4+
5+
## Imports
6+
7+
```jsx
8+
import {
9+
styl,
10+
css,
11+
pug,
12+
variables,
13+
setDefaultVariables,
14+
defaultVariables,
15+
dimensions,
16+
matcher
17+
} from 'cssxjs'
18+
```
19+
20+
## Sections
21+
22+
- [Template Literals](/api/template-literals) - `styl`, `css`, `pug`
23+
- [CSS Variables](/api/variables) - `variables`, `setDefaultVariables`, `defaultVariables`, `dimensions`
24+
- [JSX Props](/api/jsx-props) - `styleName`, `part`
25+
- [Babel Configuration](/api/babel) - Preset options and setup
26+
27+
## Quick Reference
28+
29+
| Export | Type | Description |
30+
|--------|------|-------------|
31+
| `styl` | Template literal | Write styles in Stylus syntax |
32+
| `css` | Template literal | Write styles in plain CSS syntax |
33+
| `pug` | Template literal | Write JSX in Pug syntax |
34+
| `variables` | Observable object | Set CSS variable values at runtime |
35+
| `setDefaultVariables` | Function | Set default CSS variable values |
36+
| `defaultVariables` | Object | Read-only default variable values |
37+
| `dimensions` | Observable object | Current screen width for media queries |
38+
| `matcher` | Function | Internal style matching (advanced) |

‎docs/api/jsx-props.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# JSX Props
2+
3+
CSSX extends JSX with custom props for styling.
4+
5+
## styleName
6+
7+
Apply class-based styles to an element. Works like `className` but with scoped, processed styles.
8+
9+
```jsx
10+
<div styleName="card featured">Content</div>
11+
```
12+
13+
**Syntax Options:**
14+
15+
```jsx
16+
// String
17+
<div styleName="card" />
18+
19+
// Object - keys with truthy values are included
20+
<div styleName={{ card: true, active, highlighted }} />
21+
22+
// Array - falsy values are filtered out
23+
<div styleName={['card', active && 'active']} />
24+
25+
// Mixed - combine arrays, strings, and objects (recommended)
26+
<div styleName={['button', variant, { active, disabled }]} />
27+
```
28+
29+
### Modifier Classes with Object/Array Syntax
30+
31+
The object and array syntax is cleaner than string interpolation for conditional classes. Name your variables to match the CSS class names for the cleanest syntax:
32+
33+
```jsx
34+
function Card({ highlighted, compact }) {
35+
return (
36+
// Object shorthand - cleanest when variable names match class names
37+
<div styleName={{ card: true, highlighted, compact }}>
38+
Content
39+
</div>
40+
)
41+
42+
styl`
43+
.card
44+
background white
45+
border 1px solid #ddd
46+
padding 16px
47+
.card.highlighted
48+
border-color gold
49+
box-shadow 0 0 10px gold
50+
.card.compact
51+
padding 8px
52+
`
53+
}
54+
```
55+
56+
Compare this to the less readable string interpolation:
57+
58+
```jsx
59+
// Avoid - harder to read with multiple modifiers
60+
<div styleName={`card ${highlighted ? 'highlighted' : ''} ${compact ? 'compact' : ''}`}>
61+
```
62+
63+
### Dynamic Styles
64+
65+
For truly dynamic values, combine `styleName` with the `style` prop:
66+
67+
```jsx
68+
function ProgressBar({ progress }) {
69+
return (
70+
<div styleName="bar" style={{ width: `${progress}%` }}>
71+
{progress}%
72+
</div>
73+
)
74+
75+
styl`
76+
.bar
77+
height 20px
78+
background-color #4caf50
79+
transition width 0.3s
80+
`
81+
}
82+
```
83+
84+
---
85+
86+
## part
87+
88+
Expose an element for external styling via `::part()`.
89+
90+
```jsx
91+
function Button({ children }) {
92+
return (
93+
<button part="root" styleName="button">
94+
<span part="icon">★</span>
95+
<span part="text">{children}</span>
96+
</button>
97+
)
98+
}
99+
```
100+
101+
The Babel transform automatically injects the part style props — no manual prop spreading needed.
102+
103+
Parent components can then style these parts:
104+
105+
```jsx
106+
styl`
107+
.my-button::part(icon)
108+
color gold
109+
.my-button::part(text)
110+
font-weight bold
111+
`
112+
```
113+
114+
### How Parts Work
115+
116+
1. Child component marks elements with `part="name"`
117+
2. Parent uses `::part(name)` selector to target those elements
118+
3. Babel transforms both sides to connect them automatically
119+
120+
See the [Component Parts guide](/guide/component-parts) for detailed examples.
121+
122+
---
123+
124+
## matcher
125+
126+
The internal function that matches `styleName` values against compiled styles. Advanced use only.
127+
128+
**Signature:**
129+
```ts
130+
function matcher(
131+
styleName: string,
132+
fileStyles: object,
133+
globalStyles: object,
134+
localStyles: object,
135+
inlineStyleProps: object
136+
): object
137+
```
138+
139+
**Parameters:**
140+
- `styleName` - Space-separated class names (supports classnames-like syntax)
141+
- `fileStyles` - Styles from the imported CSS file
142+
- `globalStyles` - Module-level `styl` styles
143+
- `localStyles` - Function-level `styl` styles
144+
- `inlineStyleProps` - Inline style overrides
145+
146+
**Returns:** An object with style props, including `style` and any `{part}Style` props.

0 commit comments

Comments
 (0)