@navecss/core 0.2.0 → 0.3.0

package/ATOMS.md

@@ -67,7 +67,7 @@ variants, if any.
 | Atom            | Class                 | Declarations                                                                                                              | Variants                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | --------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `interactive`   | `nave-interactive`    | `cursor: pointer;`<br>`-webkit-user-select: none;`<br>`user-select: none;`<br>`-webkit-tap-highlight-color: transparent;` | —                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `focusRing`     | `nave-focus-ring`     | `outline: none;`                                                                                                          | `:focus-visible` — `outline: var(--nave-border-width-focus) solid var(--nave-color-border-focus);`<br>`outline-offset: 2px;`                                                                                                                                                                                                                                                                                                                                   |
+| `focusRing`     | `nave-focus-ring`     | `outline: none;`                                                                                                          | `:focus-visible` — `outline-style: solid;`<br>`outline-width: var(--nave-border-width-focus, 2px);`<br>`outline-color: var(--nave-color-border-focus, currentColor);`<br>`outline-offset: 2px;`                                                                                                                                                                                                                                                                |
 | `disabledState` | `nave-disabled-state` | —                                                                                                                         | `:disabled, [aria-disabled="true"]` — `color: var(--nave-color-content-disabled);`<br>`border-color: var(--nave-color-border-disabled);`<br>`pointer-events: none;`<br>On the aria-disabled branch the element stays focusable by design: this atom only blocks pointer activation (pointer-events: none), so the component's own activation handler must also check the attribute and no-op on Enter and Space, since CSS cannot prevent keyboard activation. |
 
 ## Visual

package/CONSUMER-ATOMS.md

@@ -17,7 +17,7 @@ not.
 
 ```ts
 // src/design-system/atoms.ts
-import type { AtomDefinition } from '@navecss/core/postcss'
+import type { AtomDefinition } from '@navecss/core/atoms'
 import { media } from '@navecss/tokens/breakpoints'
 
 export const myAtoms: Record<string, AtomDefinition> = {
@@ -50,22 +50,53 @@ export const myAtoms: Record<string, AtomDefinition> = {
 
 ## Registering with the plugin
 
+On Vite, pass `extend` to the Vite plugin:
+
 ```ts
 // vite.config.ts
 import { defineConfig } from 'vite'
-import { navePlugin } from '@navecss/core/postcss'
+import { navePlugin } from '@navecss/core/vite'
 import { myAtoms } from './src/design-system/atoms'
 
 export default defineConfig({
-  // your existing options, plugins included, stay as they are
-  css: { postcss: { plugins: [navePlugin({ extend: myAtoms })] } },
+  // your existing options stay as they are; add navePlugin() to your existing plugins
+  plugins: [navePlugin({ extend: myAtoms })],
   build: { cssTarget: ['chrome125', 'edge125', 'firefox128', 'safari18', 'ios18'] },
 })
 ```
 
 `build.cssTarget` is the browser floor, in Vite's terms:
-[PostCSS plugin setup](./README.md#postcss-plugin-setup) says what goes wrong
-without it.
+[Vite plugin setup](./README.md#vite-plugin-setup) says what goes wrong
+without it. On Next.js, webpack or another pipeline that runs PostCSS plugins, pass
+the same `extend` to `navePlugin` from `@navecss/core/postcss`, in your PostCSS
+config ([PostCSS plugin setup](./README.md#postcss-plugin-setup)).
+
+**An `extend` object, written inline in a cached host's config or imported
+into it as above, does not invalidate that host's cache.** A host with a
+persistent build cache (webpack's, for instance) does not know your atoms
+module is an input to the CSS it cached, so a warm rebuild after you edit an
+atom can still ship the old value. Pass `extend` as a path to the module
+instead, and the plugin declares that file to the host as a dependency, which
+lets the host's own cache key see it (the PostCSS plugin on every stylesheet it
+processes, the Vite plugin on every stylesheet that holds a directive):
+
+```ts
+navePlugin({ extend: './src/design-system/atoms.mjs' })
+```
+
+The path is resolved from the directory the build runs in (`process.cwd()`) for
+the PostCSS plugin, and from Vite's project root for the Vite plugin, not from
+the config file, and it names a file, extension included: a package name is not
+looked up. Node's own `import()` loads it, with no bundler in between, so it has
+to be a JavaScript module or a JSON file, and its default export (or, for JSON,
+its parsed top-level value) is the atoms object: for the module above,
+`export default myAtoms`.
+
+With a path the PostCSS plugin is async: call `process(css).then(cb)`, not the
+sync `.css` getter. Either plugin re-reads the file whenever the file changes,
+so a dev server sees an edit to it without a restart. Only that file: an edit to
+a module it imports is neither re-read nor visible to the host's cache, so keep
+the atoms themselves in the file you name.
 
 ## Using consumer atoms
 
@@ -100,7 +131,9 @@ Compiles to:
     border-radius: var(--nave-radius-control);
     font-weight: var(--nave-font-weight-medium);
     &:focus-visible {
-      outline: var(--nave-border-width-focus) solid var(--nave-color-border-focus);
+      outline-style: solid;
+      outline-width: var(--nave-border-width-focus, 2px);
+      outline-color: var(--nave-color-border-focus, currentColor);
       outline-offset: 2px;
     }
     &:hover {
@@ -195,7 +228,7 @@ Container thresholds are component-specific — there is no universal
 
 ```ts
 // src/design-system/atoms.ts
-import type { AtomDefinition } from '@navecss/core/postcss'
+import type { AtomDefinition } from '@navecss/core/atoms'
 
 export const myAtoms: Record<string, AtomDefinition> = {
   adaptiveCard: {

package/LICENSE

@@ -19,3 +19,39 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+THIRD-PARTY MATERIAL
+
+This package includes material copied from or derived from the CSS Syntax
+Module Level 3 specification (css-syntax-3/Overview.bs in the w3c/csswg-drafts
+repository, at commit f971255463f01fb740e2a3a7ecfe83e319cddab9, and
+https://drafts.csswg.org/css-syntax-3/#tokenization). Copyright (c) 2026 World
+Wide Web Consortium. That specification, and the repository carrying it, are
+published under the W3C Software and Document License
+(https://www.w3.org/copyright/software-license-2023/).
+
+What is copied is implemented in src/directive/tokenizer.ts, the files in
+src/directive/tokenizer/ and src/directive/block-reader.ts, all built into the
+JavaScript under dist/: the names of the token types and of their type flags,
+the definitions of the code point classes (among them the ranges of non-ASCII
+ident code points and of non-printable code points, and the maximum allowed
+code point), the order of the steps of the tokenization algorithms, and the
+rule that tells a declaration from a qualified rule. The code implementing them
+is this package's own, and everything in this package is offered under the MIT
+licence above.
+
+This package also includes material copied from or derived from ECMA-426,
+Source map format specification (spec.emu in the tc39/ecma426 repository, at
+commit c724f0f494b44b21b651fdbd6412d3437eef0e72, and
+https://tc39.es/ecma426/#sec-base64-vlq). Copyright (c) Ecma International.
+That specification is published under Ecma's alternative copyright notice
+(https://ecma-international.org/policies/by-ipr/ecma-text-copyright-policy/).
+The base64 digits it uses are those of RFC 4648, The Base16, Base32, and
+Base64 Data Encodings (https://www.rfc-editor.org/rfc/rfc4648). Copyright (C)
+The Internet Society (2006).
+
+What is copied is implemented in src/directive/source-map.ts, built into the
+JavaScript under dist/: the member names of a version 3 source map, the
+layout of its mappings string, the base64 VLQ encoding of each field in it,
+and the base64 alphabet. The code implementing them is this package's own, and
+everything in this package is offered under the MIT licence above.