@keenmate/pure-css 1.0.0-rc07 → 1.0.0-rc08
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +491 -411
- package/README.md +184 -150
- package/dist/css/base.css +133 -67
- package/dist/css/component-reset.css +27 -0
- package/dist/css/pure-css.css +153 -75
- package/package.json +83 -81
- package/src/js/fit.js +5 -2
- package/src/scss/_base-css-variables.scss +429 -655
- package/src/scss/_layout-container.scss +168 -168
- package/src/scss/_navbar-elements.scss +10 -1
- package/src/scss/_sidebar-states.scss +2 -2
- package/src/scss/_sidebar.scss +443 -428
- package/src/scss/component-reset.scss +65 -0
- package/src/scss/reboot.scss +134 -134
- package/src/scss/scrollbars.scss +48 -48
- package/src/scss/variables/_base.scss +368 -256
- package/src/scss/variables/_colors.scss +208 -237
- package/src/scss/variables/_index.scss +27 -23
- package/src/scss/variables/_system.scss +19 -23
- package/src/scss/variables/_components.scss +0 -840
package/README.md
CHANGED
|
@@ -1,150 +1,184 @@
|
|
|
1
|
-
# @keenmate/pure-css
|
|
2
|
-
|
|
3
|
-
The KeenMate CSS **foundation** — the `--base-*` theming contract, the flexbox grid (`.pc-row` / `.pc-col`), and the
|
|
4
|
-
utility classes — extracted from [`@keenmate/pure-admin-core`](https://github.com/KeenMate/pure-admin)
|
|
5
|
-
so it can be consumed on its own.
|
|
6
|
-
|
|
7
|
-
## What's New in 1.0.0-
|
|
8
|
-
|
|
9
|
-
- **
|
|
10
|
-
- **
|
|
11
|
-
- **
|
|
12
|
-
- **Surfaces —
|
|
13
|
-
- **
|
|
14
|
-
- **
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
- **
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
1
|
+
# @keenmate/pure-css
|
|
2
|
+
|
|
3
|
+
The KeenMate CSS **foundation** — the `--base-*` theming contract, the flexbox grid (`.pc-row` / `.pc-col`), and the
|
|
4
|
+
utility classes — extracted from [`@keenmate/pure-admin-core`](https://github.com/KeenMate/pure-admin)
|
|
5
|
+
so it can be consumed on its own.
|
|
6
|
+
|
|
7
|
+
## What's New in 1.0.0-rc08
|
|
8
|
+
|
|
9
|
+
- **Foundation-only — the `--pc-*` component layer moved to `@keenmate/pure-admin-core` (breaking)** — pure-css no longer ships `variables/_components.scss` or the component emit mixins (`output-pc-component-variables`, `output-pc-component-mode-variables`, `output-pc-alert-variables-{light,dark}`) — the whole buttons / cards / tables / modals / alerts / badges / command-palette / multiselect vocabulary. pure-css is now a true foundation: the `--base-*` bridge plus the base `--pc-*` tokens (surfaces, text, accent, links, border, role identities, palette slots, radius). SCSS consumers that `@include`d the component mixins must take them from pure-admin-core ≥ 2.9.0-rc20; consumers of the compiled `dist/css/*` are unaffected.
|
|
10
|
+
- **Icons — a shared, themeable `--base-icon-*` contract (13 tokens)** — `chevron`, `caret-down`/`-up`, `close`, `clear`, `remove`, `expand`, `collapse`, `add`, `edit`, `delete`, `search` (Lucide defaults), emitted as percent-encoded SVG data-URIs painted via `mask` + `background: currentColor`. One override re-skins the shell, pure-admin components, and the web components together; the shell's sidebar/navbar chevrons are now SVG masks instead of a `›` text glyph. Two disclosure models are documented — chevron *rotates one glyph*, expand/collapse *swaps two*.
|
|
11
|
+
- **Contract — a coherent, fully-named `--base-*` token API (WS7)** — added `--base-border-width`, the `--base-primary-*` accent aliases, `--base-secondary-*`, the `--base-text-on-<role>` set, `--base-info-bg` for role symmetry, the `--base-color-1..9` (+`-text`) brand palette aliased by `--pc-color-N`, and the non-colour scales `--base-space-*`, `--base-shadow-{sm,md,lg}`, `--base-duration-*` + `--base-ease-*`, and `--base-z-*`. `--base-disabled-bg` got its own value (`#f1f3f5`) instead of colliding with the hover surface.
|
|
12
|
+
- **Surfaces — hover/active split off the recessed surface** — new `--pc-hover-bg` / `--pc-active-bg` base tokens let component hover/active states read a dedicated interaction-state axis rather than borrowing the recessed `--base-subtle-bg`, which read as *raised* in several dark themes.
|
|
13
|
+
- **Theme — default palette rebased onto pure-admin Corporate** — `$base-*` defaults now track Corporate (accent `#0ea5e9`, slate text/surfaces, emerald/red/amber/cyan roles), with the palette sourced from `$base-color-1..9`. This changes pure-css's *un-themed* default look; themed apps are unaffected since every theme sets its own `--base-*`.
|
|
14
|
+
- **Shadow DOM — a new `component-reset` entry** — `./component-reset` (`dist/css/component-reset.css`) is the counterpart to `reboot` for web components: a `:host` box-sizing + inherited-typography reset pinned to `--base-*` so a host page can't bleed into a component's shadow root. No `rem` base — pair it with `base`. Brings the build to 7 artifacts.
|
|
15
|
+
- **Internal — `@keenmate/base-css-variables` is now the canonical `--base-*` parent** — pure-css mirrors its token list into `$base-*` SCSS, and `scripts/check-base-parity.mjs` fails the build if the emitted names drift from the contract. New tokens are authored in base-css-variables first, then mirrored here.
|
|
16
|
+
|
|
17
|
+
## What's New in 1.0.0-rc07
|
|
18
|
+
|
|
19
|
+
- **Theming — one runtime knob re-themes pure-admin components and the web components together** — before rc07 the same visual token was produced twice and independently: pure-admin's `--pc-*` component tokens were baked as compile-time literals, while the KeenMate web components read `--base-*` live, so they agreed only by coincidence and diverged the instant a theme retuned `--base-*` at runtime (every dark-mode toggle does exactly this at `.pc-mode-dark`). ~40 themed `--pc-*` tokens in `_base-css-variables.scss` (buttons, cards, inputs, checkbox, input groups, tables, modal, tooltip/popover, command palette, multiselect) were rewritten from `#{$…}` literals to the guiding-rule form `var(--base-x, #{$fallback})`. The `#{$fallback}` preserves today's compiled value so light-mode output is byte-for-byte unchanged, but each token now follows any runtime `--base-*` override — the same knob the web components already read.
|
|
20
|
+
- **App shell — navbar/sidebar/footer surfaces stay a distinct brand colour, deliberately not `--base-*`-derived** — the shell's surface + text tokens (`--pc-navbar-*`, `--pc-sidebar-*`, `--pc-footer-*`) are emitted as plain `#{$…}` literals, *not* `var(--base-main-bg, …)`. A theme sets the shell's brand (e.g. a yellow navbar) independently of the `--base-*` card/page palette, and since `--base-main-bg` is always emitted, deriving the navbar from it would let the base palette win and erase the brand. Standalone (`base.css`-only) rendering still works because the shell CSS resolves `var(--pc-navbar-bg, var(--base-main-bg))` — the `--base-*` floor applies only when no `--pc-*` is emitted (the rc06 contract), never as a runtime override of it.
|
|
21
|
+
- **Theming — gap `--base-*` tokens the web components read but pure-css never emitted** — several `--base-*` vars the components already consumed were falling through to hardcoded component defaults because pure-css didn't emit them, so they couldn't be themed. rc07 emits them: `--base-text-inverted`, `--base-checkbox-border-color`, `--base-input-border-color` (+ the `--base-input-border` shorthand), `--base-input-clear-color` / `--base-input-clear-bg-hover`, the solid role fills `--base-success-bg` / `--base-danger-bg` / `--base-warning-bg`, and `--base-rem`.
|
|
22
|
+
- **Surfaces — `--pc-main-bg` / `--pc-subtle-bg` naming realigned with the `--base-*` model** — `--pc-main-bg` is now the **white surface** and `--pc-subtle-bg` the **muted grey**, matching `--base-main-bg` / `--base-subtle-bg`; previously the two were inverted (`--pc-main-bg` *was* the grey canvas). pure-css's own canvas usages (reboot `body`, `.pc-layout`, scrollbars) were repointed `--pc-main-bg` → `--pc-page-bg` so the page canvas stays grey. **Downstream code reading `--pc-main-bg` / `--pc-subtle-bg` must re-check intent** — see pure-admin-core rc19.
|
|
23
|
+
- **Fixed — input borders finally track the theme** — `$input-border` was a hardcoded `#ced4da` (its own comment wrongly claimed it came from base); it's reconnected to `$base-input-border-color`. Also a semantic surface reconciliation so pure-admin and the web components resolve the *same* base token per surface (card/table headers + striped rows → `--base-elevated-bg`, dropdown/popover → `--base-dropdown-bg`, hover → `--base-hover-bg`).
|
|
24
|
+
- **Fixed — sidebar search box alignment + collapsed-rail gating** — the search input's inline padding was rebalanced (`0 $spacing-base 0 $spacing-sm`) so its magnifier lines up with the nav-row icons below it, and the collapsed-rail rules that strip the search down to the submit icon were re-scoped from `.pc-layout__sidebar--icon-collapse` to `.sidebar-hidden .pc-layout__sidebar--icon-collapse` — the mode class stays on the element while the rail is expanded, so the unscoped rules were stripping the search frame in the expanded state too.
|
|
25
|
+
|
|
26
|
+
## Why
|
|
27
|
+
|
|
28
|
+
Any surface that isn't a full admin app — a docs site, a marketing page, a standalone widget host —
|
|
29
|
+
wants the *foundation* (variables + grid + utilities) without pure-admin-core's 40+ components. And
|
|
30
|
+
every KeenMate web component (`<web-multiselect>`, …) and Svelte component already reads its colors
|
|
31
|
+
from the `--base-*` custom properties. Shipping those from one small package means one theming layer
|
|
32
|
+
that the components, the admin framework, and everything else all agree on.
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
@keenmate/pure-css @keenmate/pure-admin-core
|
|
36
|
+
├─ --base-* variables ◀──── imports pure-css, adds
|
|
37
|
+
├─ .pc-row / .pc-col grid the component library
|
|
38
|
+
└─ utility classes
|
|
39
|
+
▲
|
|
40
|
+
└── docs sites, portals, component hosts consume the built CSS directly
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Installation
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npm install @keenmate/pure-css
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Quick Start
|
|
50
|
+
|
|
51
|
+
**Prebuilt CSS (simplest):**
|
|
52
|
+
|
|
53
|
+
```html
|
|
54
|
+
<link rel="stylesheet" href="node_modules/@keenmate/pure-css/dist/css/pure-css.css">
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
or cherry-pick:
|
|
58
|
+
|
|
59
|
+
```html
|
|
60
|
+
<link rel="stylesheet" href="…/pure-css/dist/css/base.css"> <!-- variables only -->
|
|
61
|
+
<link rel="stylesheet" href="…/pure-css/dist/css/grid.css"> <!-- + grid -->
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**SCSS (customize before compiling):**
|
|
65
|
+
|
|
66
|
+
```scss
|
|
67
|
+
// Override the source of truth; everything re-derives.
|
|
68
|
+
$base-accent-color: #4f46e5;
|
|
69
|
+
$base-page-bg: #0b1020;
|
|
70
|
+
|
|
71
|
+
@use '@keenmate/pure-css/scss/pure-css';
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## What's in it
|
|
75
|
+
|
|
76
|
+
| Artifact | Contents | When to link |
|
|
77
|
+
| --- | --- | --- |
|
|
78
|
+
| `dist/css/pure-css.css` | everything below, in one file | the common case |
|
|
79
|
+
| `dist/css/base.css` | only `:root { --base-*; --pc-*; }` | you just need the theming contract (e.g. to theme embedded web components) or a base for a theme override |
|
|
80
|
+
| `dist/css/component-reset.css` | a `:host` reset (box-sizing + inherited typography pinned to `--base-*`) — the Shadow-DOM counterpart to reboot | building a web component: adopt it into the shadow root (e.g. `import '@keenmate/pure-css/component-reset?inline'`) so the host page can't bleed styles in; pair with `base` |
|
|
81
|
+
| `dist/css/grid.css` | `.pc-row` / `.pc-col-*` (percentage + fraction columns, container-query responsive) | layout only |
|
|
82
|
+
| `dist/css/utilities.css` | spacing / flex / display / width-height utilities (`.m-4`, `.d-flex`, `.w-50`, …) | utilities only |
|
|
83
|
+
|
|
84
|
+
The `pure-css.css` bundle also includes the **app shell** (navbar, sidebar,
|
|
85
|
+
layout container) — `base.css` / `grid.css` / `utilities.css` do not.
|
|
86
|
+
|
|
87
|
+
### The app-shell runtime (`./js`)
|
|
88
|
+
|
|
89
|
+
The shell's behaviour (nav fit/collapse, dropdowns, drag-to-resize, container
|
|
90
|
+
breakpoints) ships as dependency-free source JS via the `./js` export — no
|
|
91
|
+
bundler required, drop it in with a `<script>` and call `initAll`:
|
|
92
|
+
|
|
93
|
+
```html
|
|
94
|
+
<link rel="stylesheet" href="node_modules/@keenmate/pure-css/dist/css/pure-css.css">
|
|
95
|
+
<script src="node_modules/@keenmate/pure-css/src/js/pure-css.js"></script>
|
|
96
|
+
<script src="node_modules/@keenmate/pure-css/src/js/fit.js"></script>
|
|
97
|
+
<script src="node_modules/@keenmate/pure-css/src/js/navbar-dropdown.js"></script>
|
|
98
|
+
<script src="node_modules/@keenmate/pure-css/src/js/sidebar-resize.js"></script>
|
|
99
|
+
<script>window.pureCss.components.initAll(document);</script>
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
`window.pureCss` also exposes an event bus and live `viewport` / `colorScheme` /
|
|
103
|
+
`device` sources. The runtime is optional — shell CSS is authored no-JS-safe, so
|
|
104
|
+
the styling stands on its own and the JS only adds the interactive behaviour.
|
|
105
|
+
|
|
106
|
+
### The `--base-*` contract
|
|
107
|
+
|
|
108
|
+
`--base-*` is the **single source of truth for theming**. Framework colors, component variables
|
|
109
|
+
(`--pc-*`) and web/svelte components all derive from it via fallback chains
|
|
110
|
+
(`--ms-accent-color: var(--base-accent-color, #3b82f6)`). Categories: accent, text, background,
|
|
111
|
+
border, input, dropdown, tooltip, contextual (success/danger/warning/info), interactive states,
|
|
112
|
+
typography, border-radius, spacing/shadow/motion/z-index scales, and icons. The full list is
|
|
113
|
+
`src/scss/variables/_base.scss`.
|
|
114
|
+
|
|
115
|
+
#### Icons
|
|
116
|
+
|
|
117
|
+
`--base-icon-*` are mask-friendly SVG glyphs (Lucide defaults) for the shared UI affordances, so the
|
|
118
|
+
pure-css shell, pure-admin components, and the web/svelte components render the **same** marks and a
|
|
119
|
+
theme re-skins them in one place. Each is consumed via `mask: var(--base-icon-x); background:
|
|
120
|
+
currentColor`, so the glyph inherits text colour — override a token with any mask-friendly `url()` to
|
|
121
|
+
swap the icon set.
|
|
122
|
+
|
|
123
|
+
| Token | Glyph | Use |
|
|
124
|
+
| --- | --- | --- |
|
|
125
|
+
| `--base-icon-chevron` | stroked angle `›` | expanders / nav — **rotate-one-glyph** disclosure (points right, rotate 90° when open) |
|
|
126
|
+
| `--base-icon-caret-down` / `--base-icon-caret-up` | solid triangles `▾` / `▴` | static dropdown / `<select>` affordance (down) and sort-direction / upward-dropdown counterpart (up) — a caret never rotates |
|
|
127
|
+
| `--base-icon-close` | `✕` | dismiss a transient **surface** (dialog, panel, popover, toast) |
|
|
128
|
+
| `--base-icon-clear` | `✕` | clear a **field** — distinct purpose, same glyph; **follows** `--base-icon-close`, override alone to diverge |
|
|
129
|
+
| `--base-icon-remove` | `✕` | take an **item** out of a collection (chip / tag / row) — non-destructive; follows `--base-icon-close` |
|
|
130
|
+
| `--base-icon-expand` / `--base-icon-collapse` | `+` / `−` | **swap-two-glyphs** disclosure (tree nodes, accordions): show `+` when collapsed, `−` when open |
|
|
131
|
+
| `--base-icon-add` / `--base-icon-edit` / `--base-icon-delete` | `+` / pencil / trash | **CRUD action** verbs — create / modify / **destroy** (delete is a trash can, *not* an ✕, so it reads as destructive) |
|
|
132
|
+
| `--base-icon-search` | magnifying glass | search inputs, filter fields, command palette |
|
|
133
|
+
|
|
134
|
+
Two intentional distinctions:
|
|
135
|
+
|
|
136
|
+
- **Disclosure models:** **chevron rotates one glyph** (sidebar, multiselect), while **expand/collapse swaps
|
|
137
|
+
two glyphs** (trees, accordions) — a component never rotates a `+` into a `−`.
|
|
138
|
+
- **✕ vs trash:** `close` / `clear` / `remove` are three *dismiss* purposes that share the ✕ glyph (and
|
|
139
|
+
cascade off `--base-icon-close`), while `delete` is a separate *destructive* action drawn as a trash can.
|
|
140
|
+
`add` shares the `+` shape with `expand` but is an independent knob (create ≠ disclosure).
|
|
141
|
+
|
|
142
|
+
## Theming
|
|
143
|
+
|
|
144
|
+
A **theme** is nothing but a set of `--base-*` values. The lightest possible theme is a stylesheet
|
|
145
|
+
that redeclares them, loaded *after* `base.css`:
|
|
146
|
+
|
|
147
|
+
```css
|
|
148
|
+
:root {
|
|
149
|
+
--base-accent-color: #4f46e5;
|
|
150
|
+
--base-page-bg: #f6f8fb;
|
|
151
|
+
--base-text-color-1: #1a2233;
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Because pure-admin-core, the components and any consumer all read the same variables, that one block
|
|
156
|
+
re-themes all of them at once. This is the same model as
|
|
157
|
+
[`@keenmate/pure-admin-themes`](https://github.com/KeenMate/pure-admin-themes), so the same CLI and
|
|
158
|
+
publishing infrastructure applies.
|
|
159
|
+
|
|
160
|
+
## Build
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
make install # sass
|
|
164
|
+
make build # src/scss -> dist/css (bundle + base + grid + utilities)
|
|
165
|
+
make sizes # show artifact sizes
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
`dist/` is committed so consumers can vendor the built CSS without a Sass toolchain.
|
|
169
|
+
|
|
170
|
+
## Provenance
|
|
171
|
+
|
|
172
|
+
The SCSS is the foundation extracted from `pure-admin-core`'s `src/scss` — the `variables/` modules,
|
|
173
|
+
`_base-css-variables.scss`, `utilities.scss`, `_fonts.scss`, and the native grid (`_pa-grid.scss`,
|
|
174
|
+
formerly core's `core-components/_grid.scss`). **pure-admin-core now consumes this package** as its
|
|
175
|
+
single source for the foundation (thin `@import`/`@forward` shims), so the two no longer drift —
|
|
176
|
+
core's compiled `--base-*` values and grid output match pure-css exactly.
|
|
177
|
+
|
|
178
|
+
One intentional difference: `utilities.scss` here `@use`s `_fonts.scss` so the generic
|
|
179
|
+
`.font-family-*` classes ship with the other utilities, whereas core keeps `_fonts.scss` standalone.
|
|
180
|
+
`_rtl-helpers.scss` and the component layer stay in core.
|
|
181
|
+
|
|
182
|
+
## License
|
|
183
|
+
|
|
184
|
+
MIT © KeenMate. The grid is derived from [Pure](https://purecss.io/) (Yahoo!, BSD).
|