@keenmate/pure-css 1.0.0-rc08 → 1.0.0-rc09

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.
Files changed (9) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +179 -184
  3. package/dist/css/pure-css.css +8 -8
  4. package/package.json +1 -1
  5. package/src/scss/_fit-flyout.scss +1 -1
  6. package/src/scss/_navbar-elements.scss +4 -4
  7. package/src/scss/_resize-handle.scss +1 -1
  8. package/src/scss/_sidebar.scss +443 -443
  9. package/src/scss/variables/_base.scss +368 -368
package/CHANGELOG.md CHANGED
@@ -3,6 +3,28 @@
3
3
  All notable changes to `@keenmate/pure-css` are documented here. Format based on
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
5
5
 
6
+ ## [1.0.0-rc09] — 2026-09-10 [PUBLISHED]
7
+
8
+ The **shell/namespace decoupling** release. Part of the ecosystem-wide
9
+ `--pc-*` → `--pa-*` component-token rename (custom-property prefix now matches
10
+ class prefix: `--pc-*`/`.pc-*` = pure-css foundation + shell, `--pa-*`/`.pa-*` =
11
+ pure-admin components). pure-css owns none of the renamed tokens; this release
12
+ only removes the shell's few incidental references to pure-admin component
13
+ tokens so the foundation never points into pure-admin's namespace.
14
+
15
+ ### Changed
16
+
17
+ - **The app shell no longer references pure-admin component tokens.** Three shell
18
+ surfaces read a `--pc-*` *component* token as the first tier of a fallback
19
+ chain — the fit-flyout, navbar dropdown and resize-handle used
20
+ `var(--pc-card-bg, var(--base-main-bg))`; the sidebar search used
21
+ `var(--pc-input-bg, var(--base-input-bg))`; and the sidebar/navbar chevrons
22
+ used `var(--pc-icon-chevron, var(--base-icon-chevron, …))`. Those component
23
+ tokens are being renamed to `--pa-*` (pure-admin's namespace), which the
24
+ foundation must not depend on, so each reference now reads its `--base-*`
25
+ foundation value directly. **Rendered output is unchanged** — every dropped
26
+ tier resolved to the same `--base-*` fallback already.
27
+
6
28
  ## [1.0.0-rc08] — 2026-09-10 [PUBLISHED]
7
29
 
8
30
  The **foundation-only + coherent-contract** release. rc08 finishes what rc07
package/README.md CHANGED
@@ -1,184 +1,179 @@
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).
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-rc09
8
+
9
+ - **Namespace hygiene — the app shell no longer reaches into pure-admin's token namespace** — the KeenMate ecosystem is aligning its custom-property prefixes with its class prefixes: `--pc-*` / `.pc-*` belong to the pure-css foundation + app shell, `--pa-*` / `.pa-*` belong to pure-admin components. As part of that rename, pure-css's shell had a handful of incidental references to *component* tokens — `var(--pc-card-bg, …)` in the fit-flyout / navbar dropdown / resize-handle, `var(--pc-input-bg, …)` in the sidebar search, and `var(--pc-icon-chevron, …)` on the sidebar/navbar chevrons. Since those tokens are moving to `--pa-*` (pure-admin's namespace) and the foundation must not depend on pure-admin, each now reads its `--base-*` foundation value directly. Rendered output is byte-for-byte unchanged — every dropped tier already resolved to the same `--base-*` fallback.
10
+
11
+ ## What's New in 1.0.0-rc08
12
+
13
+ - **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.
14
+ - **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*.
15
+ - **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.
16
+ - **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.
17
+ - **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-*`.
18
+ - **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.
19
+ - **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.
20
+
21
+ ## Why
22
+
23
+ Any surface that isn't a full admin app — a docs site, a marketing page, a standalone widget host —
24
+ wants the *foundation* (variables + grid + utilities) without pure-admin-core's 40+ components. And
25
+ every KeenMate web component (`<web-multiselect>`, …) and Svelte component already reads its colors
26
+ from the `--base-*` custom properties. Shipping those from one small package means one theming layer
27
+ that the components, the admin framework, and everything else all agree on.
28
+
29
+ ```
30
+ @keenmate/pure-css @keenmate/pure-admin-core
31
+ ├─ --base-* variables ◀──── imports pure-css, adds
32
+ ├─ .pc-row / .pc-col grid the component library
33
+ └─ utility classes
34
+ ▲
35
+ └── docs sites, portals, component hosts consume the built CSS directly
36
+ ```
37
+
38
+ ## Installation
39
+
40
+ ```bash
41
+ npm install @keenmate/pure-css
42
+ ```
43
+
44
+ ## Quick Start
45
+
46
+ **Prebuilt CSS (simplest):**
47
+
48
+ ```html
49
+ <link rel="stylesheet" href="node_modules/@keenmate/pure-css/dist/css/pure-css.css">
50
+ ```
51
+
52
+ or cherry-pick:
53
+
54
+ ```html
55
+ <link rel="stylesheet" href="…/pure-css/dist/css/base.css"> <!-- variables only -->
56
+ <link rel="stylesheet" href="…/pure-css/dist/css/grid.css"> <!-- + grid -->
57
+ ```
58
+
59
+ **SCSS (customize before compiling):**
60
+
61
+ ```scss
62
+ // Override the source of truth; everything re-derives.
63
+ $base-accent-color: #4f46e5;
64
+ $base-page-bg: #0b1020;
65
+
66
+ @use '@keenmate/pure-css/scss/pure-css';
67
+ ```
68
+
69
+ ## What's in it
70
+
71
+ | Artifact | Contents | When to link |
72
+ | --- | --- | --- |
73
+ | `dist/css/pure-css.css` | everything below, in one file | the common case |
74
+ | `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 |
75
+ | `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` |
76
+ | `dist/css/grid.css` | `.pc-row` / `.pc-col-*` (percentage + fraction columns, container-query responsive) | layout only |
77
+ | `dist/css/utilities.css` | spacing / flex / display / width-height utilities (`.m-4`, `.d-flex`, `.w-50`, …) | utilities only |
78
+
79
+ The `pure-css.css` bundle also includes the **app shell** (navbar, sidebar,
80
+ layout container) — `base.css` / `grid.css` / `utilities.css` do not.
81
+
82
+ ### The app-shell runtime (`./js`)
83
+
84
+ The shell's behaviour (nav fit/collapse, dropdowns, drag-to-resize, container
85
+ breakpoints) ships as dependency-free source JS via the `./js` export — no
86
+ bundler required, drop it in with a `<script>` and call `initAll`:
87
+
88
+ ```html
89
+ <link rel="stylesheet" href="node_modules/@keenmate/pure-css/dist/css/pure-css.css">
90
+ <script src="node_modules/@keenmate/pure-css/src/js/pure-css.js"></script>
91
+ <script src="node_modules/@keenmate/pure-css/src/js/fit.js"></script>
92
+ <script src="node_modules/@keenmate/pure-css/src/js/navbar-dropdown.js"></script>
93
+ <script src="node_modules/@keenmate/pure-css/src/js/sidebar-resize.js"></script>
94
+ <script>window.pureCss.components.initAll(document);</script>
95
+ ```
96
+
97
+ `window.pureCss` also exposes an event bus and live `viewport` / `colorScheme` /
98
+ `device` sources. The runtime is optional — shell CSS is authored no-JS-safe, so
99
+ the styling stands on its own and the JS only adds the interactive behaviour.
100
+
101
+ ### The `--base-*` contract
102
+
103
+ `--base-*` is the **single source of truth for theming**. Framework colors, component variables
104
+ (`--pc-*`) and web/svelte components all derive from it via fallback chains
105
+ (`--ms-accent-color: var(--base-accent-color, #3b82f6)`). Categories: accent, text, background,
106
+ border, input, dropdown, tooltip, contextual (success/danger/warning/info), interactive states,
107
+ typography, border-radius, spacing/shadow/motion/z-index scales, and icons. The full list is
108
+ `src/scss/variables/_base.scss`.
109
+
110
+ #### Icons
111
+
112
+ `--base-icon-*` are mask-friendly SVG glyphs (Lucide defaults) for the shared UI affordances, so the
113
+ pure-css shell, pure-admin components, and the web/svelte components render the **same** marks and a
114
+ theme re-skins them in one place. Each is consumed via `mask: var(--base-icon-x); background:
115
+ currentColor`, so the glyph inherits text colour — override a token with any mask-friendly `url()` to
116
+ swap the icon set.
117
+
118
+ | Token | Glyph | Use |
119
+ | --- | --- | --- |
120
+ | `--base-icon-chevron` | stroked angle `›` | expanders / nav — **rotate-one-glyph** disclosure (points right, rotate 90° when open) |
121
+ | `--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 |
122
+ | `--base-icon-close` | `✕` | dismiss a transient **surface** (dialog, panel, popover, toast) |
123
+ | `--base-icon-clear` | `✕` | clear a **field** — distinct purpose, same glyph; **follows** `--base-icon-close`, override alone to diverge |
124
+ | `--base-icon-remove` | `✕` | take an **item** out of a collection (chip / tag / row) — non-destructive; follows `--base-icon-close` |
125
+ | `--base-icon-expand` / `--base-icon-collapse` | `+` / `−` | **swap-two-glyphs** disclosure (tree nodes, accordions): show `+` when collapsed, `−` when open |
126
+ | `--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) |
127
+ | `--base-icon-search` | magnifying glass | search inputs, filter fields, command palette |
128
+
129
+ Two intentional distinctions:
130
+
131
+ - **Disclosure models:** **chevron rotates one glyph** (sidebar, multiselect), while **expand/collapse swaps
132
+ two glyphs** (trees, accordions) — a component never rotates a `+` into a `−`.
133
+ - **✕ vs trash:** `close` / `clear` / `remove` are three *dismiss* purposes that share the ✕ glyph (and
134
+ cascade off `--base-icon-close`), while `delete` is a separate *destructive* action drawn as a trash can.
135
+ `add` shares the `+` shape with `expand` but is an independent knob (create ≠ disclosure).
136
+
137
+ ## Theming
138
+
139
+ A **theme** is nothing but a set of `--base-*` values. The lightest possible theme is a stylesheet
140
+ that redeclares them, loaded *after* `base.css`:
141
+
142
+ ```css
143
+ :root {
144
+ --base-accent-color: #4f46e5;
145
+ --base-page-bg: #f6f8fb;
146
+ --base-text-color-1: #1a2233;
147
+ }
148
+ ```
149
+
150
+ Because pure-admin-core, the components and any consumer all read the same variables, that one block
151
+ re-themes all of them at once. This is the same model as
152
+ [`@keenmate/pure-admin-themes`](https://github.com/KeenMate/pure-admin-themes), so the same CLI and
153
+ publishing infrastructure applies.
154
+
155
+ ## Build
156
+
157
+ ```bash
158
+ make install # sass
159
+ make build # src/scss -> dist/css (bundle + base + grid + utilities)
160
+ make sizes # show artifact sizes
161
+ ```
162
+
163
+ `dist/` is committed so consumers can vendor the built CSS without a Sass toolchain.
164
+
165
+ ## Provenance
166
+
167
+ The SCSS is the foundation extracted from `pure-admin-core`'s `src/scss` — the `variables/` modules,
168
+ `_base-css-variables.scss`, `utilities.scss`, `_fonts.scss`, and the native grid (`_pa-grid.scss`,
169
+ formerly core's `core-components/_grid.scss`). **pure-admin-core now consumes this package** as its
170
+ single source for the foundation (thin `@import`/`@forward` shims), so the two no longer drift —
171
+ core's compiled `--base-*` values and grid output match pure-css exactly.
172
+
173
+ One intentional difference: `utilities.scss` here `@use`s `_fonts.scss` so the generic
174
+ `.font-family-*` classes ship with the other utilities, whereas core keeps `_fonts.scss` standalone.
175
+ `_rtl-helpers.scss` and the component layer stay in core.
176
+
177
+ ## License
178
+
179
+ MIT © KeenMate. The grid is derived from [Pure](https://purecss.io/) (Yahoo!, BSD).
package/dist/css/pure-css.css CHANGED
@@ -2070,7 +2070,7 @@ body.pc-container-2xl .pc-navbar {
2070
2070
  top: 100%;
2071
2071
  inset-inline-start: 0;
2072
2072
  min-width: 19.2rem;
2073
- background-color: var(--pc-card-bg, var(--base-main-bg));
2073
+ background-color: var(--base-main-bg);
2074
2074
  border: 1px solid var(--pc-border-color);
2075
2075
  border-radius: var(--pc-border-radius);
2076
2076
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
@@ -2154,8 +2154,8 @@ body.pc-container-2xl .pc-navbar {
2154
2154
  flex-shrink: 0;
2155
2155
  font-size: 0;
2156
2156
  background-color: currentColor;
2157
- -webkit-mask: var(--pc-icon-chevron, var(--base-icon-chevron, url("data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22 fill=%22none%22 stroke=%22%23000%22 stroke-width=%222%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22%3E%3Cpath d=%22m9 18 6-6-6-6%22/%3E%3C/svg%3E"))) center/1.1rem no-repeat;
2158
- mask: var(--pc-icon-chevron, var(--base-icon-chevron, url("data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22 fill=%22none%22 stroke=%22%23000%22 stroke-width=%222%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22%3E%3Cpath d=%22m9 18 6-6-6-6%22/%3E%3C/svg%3E"))) center/1.1rem no-repeat;
2157
+ -webkit-mask: var(--base-icon-chevron, url("data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22 fill=%22none%22 stroke=%22%23000%22 stroke-width=%222%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22%3E%3Cpath d=%22m9 18 6-6-6-6%22/%3E%3C/svg%3E")) center/1.1rem no-repeat;
2158
+ mask: var(--base-icon-chevron, url("data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22 fill=%22none%22 stroke=%22%23000%22 stroke-width=%222%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22%3E%3Cpath d=%22m9 18 6-6-6-6%22/%3E%3C/svg%3E")) center/1.1rem no-repeat;
2159
2159
  transition: transform 0.1s ease-out;
2160
2160
  }
2161
2161
  .pc-navmenu__item--more.is-open .pc-navmenu__more-chevron {
@@ -2320,7 +2320,7 @@ body.pc-container-2xl .pc-navbar {
2320
2320
  width: 14px;
2321
2321
  height: 44px;
2322
2322
  border-radius: min(var(--pc-border-radius-lg), 4px);
2323
- background-color: var(--pc-card-bg, var(--base-main-bg));
2323
+ background-color: var(--base-main-bg);
2324
2324
  border: 2px solid var(--pc-border-color);
2325
2325
  color: var(--pc-text-color-2);
2326
2326
  font-size: 1.8rem;
@@ -2431,7 +2431,7 @@ body.loaded .pc-sidebar__link {
2431
2431
  height: 3.5rem;
2432
2432
  padding: 0 1.6rem 0 0.8rem;
2433
2433
  color: var(--pc-text-color-2);
2434
- background-color: var(--pc-input-bg, var(--base-input-bg));
2434
+ background-color: var(--base-input-bg);
2435
2435
  border: 1px solid var(--pc-border-color);
2436
2436
  border-radius: var(--pc-border-radius);
2437
2437
  text-align: start;
@@ -2585,8 +2585,8 @@ body.loaded .pc-sidebar__label {
2585
2585
  flex-shrink: 0;
2586
2586
  font-size: 0;
2587
2587
  background-color: currentColor;
2588
- -webkit-mask: var(--pc-icon-chevron, var(--base-icon-chevron, url("data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22 fill=%22none%22 stroke=%22%23000%22 stroke-width=%222%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22%3E%3Cpath d=%22m9 18 6-6-6-6%22/%3E%3C/svg%3E"))) center/1.2rem no-repeat;
2589
- mask: var(--pc-icon-chevron, var(--base-icon-chevron, url("data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22 fill=%22none%22 stroke=%22%23000%22 stroke-width=%222%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22%3E%3Cpath d=%22m9 18 6-6-6-6%22/%3E%3C/svg%3E"))) center/1.2rem no-repeat;
2588
+ -webkit-mask: var(--base-icon-chevron, url("data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22 fill=%22none%22 stroke=%22%23000%22 stroke-width=%222%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22%3E%3Cpath d=%22m9 18 6-6-6-6%22/%3E%3C/svg%3E")) center/1.2rem no-repeat;
2589
+ mask: var(--base-icon-chevron, url("data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 24 24%22 fill=%22none%22 stroke=%22%23000%22 stroke-width=%222%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22%3E%3Cpath d=%22m9 18 6-6-6-6%22/%3E%3C/svg%3E")) center/1.2rem no-repeat;
2590
2590
  }
2591
2591
  body.loaded .pc-sidebar__chevron {
2592
2592
  transition: transform 0.1s ease-out;
@@ -3115,7 +3115,7 @@ body.pc-layout--sticky .pc-layout__inner {
3115
3115
  min-width: 20rem;
3116
3116
  max-width: 32rem;
3117
3117
  padding: 0.8rem;
3118
- background: var(--pc-card-bg, var(--base-main-bg));
3118
+ background: var(--base-main-bg);
3119
3119
  border: 1px solid var(--pc-border-color);
3120
3120
  border-radius: var(--pc-border-radius);
3121
3121
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@keenmate/pure-css",
3
- "version": "1.0.0-rc08",
3
+ "version": "1.0.0-rc09",
4
4
  "description": "The KeenMate CSS foundation — --base-* theming contract, PureCSS grid and utility classes. Extracted from pure-admin-core so docs sites, standalone pages and every web/svelte component share one theming layer.",
5
5
  "style": "dist/css/pure-css.css",
6
6
  "exports": {
package/src/scss/_fit-flyout.scss CHANGED
@@ -60,7 +60,7 @@
60
60
  min-width: 20rem;
61
61
  max-width: 32rem;
62
62
  padding: $spacing-sm;
63
- background: var(--pc-card-bg, var(--base-main-bg));
63
+ background: var(--base-main-bg);
64
64
  border: $border-width-base solid var(--pc-border-color);
65
65
  border-radius: var(--pc-border-radius);
66
66
  box-shadow: $shadow-lg;
package/src/scss/_navbar-elements.scss CHANGED
@@ -142,7 +142,7 @@
142
142
  top: 100%;
143
143
  inset-inline-start: 0; // RTL: flips to right: 0
144
144
  min-width: 19.2rem;
145
- background-color: var(--pc-card-bg, var(--base-main-bg));
145
+ background-color: var(--base-main-bg);
146
146
  border: $border-width-base solid var(--pc-border-color);
147
147
  border-radius: var(--pc-border-radius);
148
148
  box-shadow: $shadow-lg;
@@ -257,7 +257,7 @@
257
257
  }
258
258
 
259
259
  // SVG mask chevron (was a "›" text glyph). Shares --base-icon-chevron with the
260
- // sidebar + components; --pc-icon-chevron overrides, #{$base-icon-chevron} is
260
+ // sidebar + components; --pa-icon-chevron (core) overrides, #{$base-icon-chevron} is
261
261
  // the standalone fallback. `font-size: 0` hides any legacy "›" in old markup.
262
262
  &__more-chevron {
263
263
  display: inline-block;
@@ -267,8 +267,8 @@
267
267
  flex-shrink: 0;
268
268
  font-size: 0;
269
269
  background-color: currentColor;
270
- -webkit-mask: var(--pc-icon-chevron, var(--base-icon-chevron, #{$base-icon-chevron})) center / 1.1rem no-repeat;
271
- mask: var(--pc-icon-chevron, var(--base-icon-chevron, #{$base-icon-chevron})) center / 1.1rem no-repeat;
270
+ -webkit-mask: var(--base-icon-chevron, #{$base-icon-chevron}) center / 1.1rem no-repeat;
271
+ mask: var(--base-icon-chevron, #{$base-icon-chevron}) center / 1.1rem no-repeat;
272
272
  transition: transform $transition-fast $easing-snappy;
273
273
  }
274
274
 
package/src/scss/_resize-handle.scss CHANGED
@@ -46,7 +46,7 @@ $resize-knob-radius-lg: 6px !default;
46
46
  // themes (radius 0) stay square via min(). High-contrast fill / border / shadow
47
47
  // so the knob stands out on both light and dark surfaces.
48
48
  border-radius: min(var(--pc-border-radius-lg), #{$resize-knob-radius});
49
- background-color: var(--pc-card-bg, var(--base-main-bg));
49
+ background-color: var(--base-main-bg);
50
50
  border: $border-width-medium solid var(--pc-border-color);
51
51
  color: var(--pc-text-color-2);
52
52
  font-size: $font-size-lg;