@abuzareal/contour-ui 0.1.1 → 0.1.2

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 (5) hide show
  1. package/CHANGELOG.md +70 -11
  2. package/README.md +124 -76
  3. package/RELEASING.md +14 -2
  4. package/dist/fonts-latin.css +35 -0
  5. package/package.json +14 -6
package/CHANGELOG.md CHANGED
@@ -1,20 +1,79 @@
1
1
  # Changelog
2
2
 
3
+ Changes to the published `@abuzareal/contour-ui` package. Version headings refer to package versions, not catalogue or application versions. Consumer projects pin their own version and update separately.
4
+
5
+ ## 0.1.2 — 2026-10-07
6
+
7
+ An optional font-loading entry and clearer setup documentation. Component APIs and runtime dependencies are unchanged from 0.1.1.
8
+
9
+ ### Added
10
+
11
+ - `fonts-latin.css`: load Latin WOFF2 files for the three system typefaces. The existing `fonts.css` retains full character coverage.
12
+
13
+ ### Documentation
14
+
15
+ - Clarify installation, CSS import order, public exports, optional dependencies, and upgrade guidance.
16
+ - Pair live examples with their source code on the documentation site. Site navigation, theme transitions, responsive layouts, and the homepage specimen were refined; these site changes do not alter package component APIs.
17
+
18
+ ### Compatibility
19
+
20
+ - React 18 and 19 remain supported. Three.js and Lenis remain optional. Packed optional-entry checks cover strict TypeScript declarations and production builds.
21
+
22
+ ### Upgrading from 0.1.1
23
+
24
+ ```sh
25
+ npm install @abuzareal/contour-ui@0.1.2 --save-exact
26
+ ```
27
+
28
+ No component changes are required. To use the smaller Latin font set, replace your `fonts.css` import with `@abuzareal/contour-ui/fonts-latin.css`. Keep the existing import for additional character coverage. Update your manifest and lockfile and check your application's rendered text.
29
+
3
30
  ## 0.1.1
4
31
 
5
- - Lock background scrolling while a Dialog or drawer is open. Nested dialogs retain the lock until the last closes; closing or unmounting restores existing document styles and scrollbar space.
32
+ A compatibility and interaction update for apps using React 18.3.1 or React 19.
33
+
34
+ ### Compatibility
6
35
 
7
- - Support React and React DOM 19 alongside 18.3.1, verified with strict clean-consumer installs, declaration checks, production builds, and runtime tests on 18.3.1, 19.0.0, and 19.3.0.
8
- - Preserve flip-card inert faces in both React majors, accept nullable refs in public hooks, and initialize the clipboard timer ref explicitly for React 19 types.
9
- - Let text fields, text areas, and select fields accept caller IDs and retain caller descriptions; keep controlled text counters synchronized with programmatic values.
10
- - Prevent theme buttons from submitting forms, and show final count-up values when IntersectionObserver is unavailable.
11
- - Document direct package imports and retain a repeatable compatibility check before publication.
36
+ - Extend the React and React DOM peer ranges to React 19. The compatibility script checks packed consumers on 18.3.1, 19.0.0, and 19.3.0 and compiles library source against React 19 types.
37
+ - Preserve inert flip-card faces in both React majors, accept nullable refs in public hooks, and initialize the clipboard timer ref for React 19 types.
38
+
39
+ ### Fixes
40
+
41
+ - **Dialog and drawers:** lock background scrolling while open. Nested dialogs retain the lock until the last closes; closing or unmounting restores the document's previous styles and scrollbar space. Dialog content remains scrollable on short screens.
42
+ - **TextField, TextArea, SelectField:** accept caller IDs and retain caller `aria-describedby` references alongside field hints and errors.
43
+ - **Text counters:** reflect programmatic changes to controlled values.
44
+ - **ThemeToggle:** use a button type that doesn't submit an enclosing form.
45
+ - **CountUp:** show the final value when IntersectionObserver is unavailable.
46
+
47
+ ### Upgrading from 0.1.0
48
+
49
+ ```sh
50
+ npm install @abuzareal/contour-ui@0.1.1 --save-exact
51
+ ```
52
+
53
+ Commit `package.json` and `package-lock.json`, then run your app's checks. Review dialogs and drawers on short screens and with nested overlays. If your app has its own background-scroll workaround, test its interaction with the library lock before removing it. Check caller-supplied field IDs/descriptions and controlled counter updates.
54
+
55
+ React 18.3.1 remains supported; adopting React 19 isn't required. Three.js and Lenis remain optional peers behind `/three` and `/scroll`. The 3D API remains experimental. The compatibility matrix doesn't establish React Server Component support or universal framework compatibility.
56
+
57
+ ### Developer tooling
58
+
59
+ - Document direct package imports and add a repeatable packed-consumer compatibility check before publication.
12
60
 
13
61
  ## 0.1.0
14
62
 
15
- - Extract reusable React components, theme tokens, styling, and optional 3D/scroll entries from the standalone design-system app.
16
- - Synchronize theme controls, tolerate blocked preference storage, and honor system reduced motion for theme changes.
17
- - Reject executable link schemes, preserve tooltip descriptions, make hidden flip-card faces inert, and handle empty tabs and zero-range sliders.
18
- - Ship typed ESM exports, optional font/reset styles, regression tests, and archive-content validation.
63
+ The first package release, extracted from the portfolio and standalone catalogue.
64
+
65
+ ### Added
66
+
67
+ - Reusable React components, theme tokens, CSS, and separate optional 3D and smooth-scroll entries.
68
+ - Typed ESM exports with font and reset styles available as opt-in imports.
69
+ - Regression tests, archive-content checks, and consumer build validation.
70
+
71
+ ### Interaction behavior
72
+
73
+ - Synchronize theme controls, tolerate blocked preference storage, and respect system reduced motion for theme changes.
74
+ - Reject executable link schemes, preserve tooltip descriptions, and make hidden flip-card faces inert.
75
+ - Handle empty tab lists and zero-range sliders.
76
+
77
+ ### Compatibility at release
19
78
 
20
- This is the first release. The 3D interface is experimental; React 19 compatibility has not been verified.
79
+ React 18.3.1 was the verified baseline for 0.1.0; React 19 compatibility was added in 0.1.1. The 3D API was introduced as experimental.
package/README.md CHANGED
@@ -1,139 +1,187 @@
1
1
  # Contour UI
2
2
 
3
- An independent React component library for editorial interfaces: paper and ink surfaces, an acid accent, readable typography, restrained motion, and optional Three.js objects.
3
+ React components and CSS tokens for interfaces with paper and ink surfaces, a lime accent, and light and dark themes. Contour started as the shared UI in a personal portfolio; it now supplies components to the portfolio, its catalogue, Atmos, and Orbit.
4
4
 
5
- The npm package is public under MIT; the development repository is private. Public consumers can inspect the distributed JavaScript, declarations, and CSS, but the repository and its issue tracker are accessible only to invited collaborators.
5
+ Use it when you want this visual style with typed controls, feedback, navigation, and motion. Applications own their layouts, data, validation, and workflows. Three.js scenes and smooth scrolling are separate, optional entries.
6
6
 
7
- **Status:** `0.1.1` compatibility update. React 18.3.1 and React 19 are supported; the packed-package matrix checks React 18.3.1, 19.0.0, and 19.3.0. React Server Component execution is not advertised as tested. Interactive components belong in a client boundary in frameworks such as Next.js. The root module can be imported on the server, and basic components can render there.
7
+ [Live catalogue](https://contour.abuzr.in/) · [npm package](https://www.npmjs.com/package/@abuzareal/contour-ui) · [Maintainer](https://github.com/abuzareal)
8
+
9
+ The catalogue currently uses **0.1.1**; this release is **0.1.2**. Catalogue examples include application patterns as well as package components. Check the exports below before treating an example as an importable component.
8
10
 
9
11
  ## Install
10
12
 
13
+ Use an existing React application with a bundler that resolves package CSS imports. Contour ships ESM and TypeScript declarations. The package declares Node.js 22 or newer; repository tooling uses Vite 8, which needs Node.js 22.12+ or 24+.
14
+
11
15
  ```sh
12
- npm install @abuzareal/contour-ui
13
- # Your application must supply matching React and React DOM versions:
14
- # React 18.3.1 or React 19.
16
+ npm install @abuzareal/contour-ui@0.1.2 --save-exact
15
17
  ```
16
18
 
19
+ Your app must provide matching `react` and `react-dom` versions: **18.3.1 or React 19**. The compatibility script covers 18.3.1, 19.0.0, and 19.3.0; it doesn't establish support for every framework or React Server Component setup. Put interactive components inside a client boundary when your framework requires one.
20
+
21
+ ## First component
22
+
23
+ Import the styles once in your application entry. Import components directly from the package; no generated files or local re-exports are needed.
24
+
17
25
  ```tsx
18
- import "@abuzareal/contour-ui/reset.css"; // optional, global reset; omit with an existing reset
19
- import "@abuzareal/contour-ui/fonts.css"; // optional, self-hosted font assets bundled by your app
26
+ import { useState } from "react";
27
+ import "@abuzareal/contour-ui/reset.css";
28
+ import "@abuzareal/contour-ui/fonts.css";
20
29
  import "@abuzareal/contour-ui/styles.css";
21
- import {
22
- Button,
23
- TextField,
24
- ToastProvider,
25
- ThemeToggle,
26
- } from "@abuzareal/contour-ui";
27
-
28
- export function App() {
30
+ import { Button, TextField, ThemeToggle } from "@abuzareal/contour-ui";
31
+
32
+ export default function App() {
33
+ const [name, setName] = useState("");
34
+ const [savedName, setSavedName] = useState("");
35
+
29
36
  return (
30
- <ToastProvider>
31
- <main data-motion="off">
32
- <ThemeToggle animate={false} />
33
- <TextField label="City" placeholder="Pune" />
34
- <Button variant="accent">Show forecast</Button>
35
- </main>
36
- </ToastProvider>
37
+ <main data-motion="off">
38
+ <ThemeToggle animate={false} />
39
+ <TextField
40
+ label="Name"
41
+ value={name}
42
+ onChange={(event) => setName(event.target.value)}
43
+ />
44
+ <Button variant="accent" onClick={() => setSavedName(name)}>
45
+ Save locally
46
+ </Button>
47
+ <p role="status">{savedName && `Saved for this session: ${savedName}`}</p>
48
+ </main>
37
49
  );
38
50
  }
39
51
  ```
40
52
 
41
- For an app with its own reset, include equivalent native button/input defaults, border-box sizing, focus outlines, and the `[hidden]` rule. Styles use globally named component classes and `:root` theme tokens; they are not Shadow DOM isolated. Avoid redefining generic classes such as `.card` or `.button` elsewhere.
53
+ This example keeps the value in React state until the component unmounts. To persist it or send it to a server, add that behavior in your app.
42
54
 
43
- ## Direct imports: no local component files required
55
+ `Button` and ordinary controls need no provider. Toasts require `ToastProvider` around components that call `useToast()`.
44
56
 
45
- Use named imports directly in any component file:
57
+ ### Optional Latin fonts
58
+
59
+ `fonts-latin.css`, added in 0.1.2, keeps DM Sans, Space Grotesk, and DM Mono while loading only Latin WOFF2 files. Use it instead of `fonts.css` for Latin text; keep `fonts.css` when the additional character sets are needed. Existing font imports continue to work.
46
60
 
47
61
  ```tsx
48
- import { Button } from "@abuzareal/contour-ui";
62
+ import "@abuzareal/contour-ui/fonts-latin.css";
63
+ ```
49
64
 
50
- export function SaveAction() {
51
- return (
52
- <Button variant="accent" onClick={() => console.log("Saved")}>
53
- Save
54
- </Button>
55
- );
65
+ ## Styles and customization
66
+
67
+ | Import | Purpose |
68
+ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
69
+ | `styles.css` | Required for the supplied appearance: tokens, component styles, and utilities. |
70
+ | `reset.css` | Optional global reset. Omit it if your app already has equivalent native-control defaults, border-box sizing, focus styles, and a `[hidden]` rule. |
71
+ | `fonts-latin.css` | Optional Latin-only WOFF2 fonts, available since 0.1.2. Use instead of `fonts.css`, not alongside it. |
72
+ | `fonts.css` | Optional self-hosted Space Grotesk, DM Sans, and DM Mono via Fontsource. Your bundler emits the font assets. |
73
+ | `tokens.css` | Tokens alone, for an app that supplies its own component styles. Already included by `styles.css`. |
74
+
75
+ Override semantic tokens after importing the styles:
76
+
77
+ ```css
78
+ :root {
79
+ --font-sans: system-ui, sans-serif;
80
+ --font-display: system-ui, sans-serif;
81
+ }
82
+
83
+ :root[data-theme="dark"] {
84
+ --bg: #111411;
85
+ --fg: #edf0e8;
56
86
  }
57
87
  ```
58
88
 
59
- Import `styles.css` once at the application entry. `reset.css` and `fonts.css` are optional. No provider is needed for `Button` or ordinary controls; only toast consumers require `ToastProvider`.
89
+ Styles use global component classes and document-level theme tokens. Scope your application's classes to avoid collisions with names such as `.card` and `.button`. Contour's CSS isn't isolated with Shadow DOM or CSS Modules.
90
+
91
+ The three Fontsource packages and `lucide-react` are direct dependencies. Omitting `fonts.css` keeps its font assets out of your application's bundle; the font packages still install. React and React DOM are peers. Three.js and Lenis are optional peers. Development tools aren't installed as Contour's consumer dependencies; tests and tooling are excluded from the npm archive.
60
92
 
61
- The original Portfolio and Design-System applications retained thin compatibility re-exports to preserve their pre-package imports. Those files are an application migration choice, not a requirement of this library. Create a wrapper only when it represents your own reusable application behavior.
93
+ ## Theme and motion
62
94
 
63
- Text fields accept explicit `id` values and preserve your `aria-describedby` references alongside their own hint or error. Native props follow the documented component types; not every component currently accepts `className`, DOM refs, or arbitrary native attributes. Do not assume router `asChild` composition or form-library ref integration is available in this release.
95
+ Set `data-theme="light"` or `"dark"` on `<html>`. `ThemeToggle` and `useTheme(animate)` read the same document state. The hook returns `{ theme, toggle }`; call `toggle(buttonElement)` from a user action. Preferences use the `aa-theme` local-storage key and are local to the site's origin.
64
96
 
65
- ## Theme and motion setup
97
+ For theme selection before first paint, inject `themeBootstrapScript` from `@abuzareal/contour-ui/theme-bootstrap` into the HTML head at build time. The exported string has no user interpolation. With a strict Content Security Policy, authorize that script with a nonce or hash.
66
98
 
67
- All theme toggles read the same document state. Set `data-theme="light"` or `"dark"` on `<html>`. `useTheme(animate)` returns `{ theme, toggle }`; call `toggle(buttonElement)` for a user action. The existing `aa-theme` local-storage key is preserved for compatibility with the original portfolio. Preference storage is origin-local, not shared across different website domains.
99
+ `useMotionPreference()` returns whether the user prefers reduced motion. Combine it with your app's pause state, set `data-motion="off"` on the app wrapper when needed, and pass `motionEnabled` to scenes and `animate` to theme controls. System reduced motion also disables the theme reveal.
68
100
 
69
- To avoid a first-paint theme flash, inject the exported static `themeBootstrapScript` from `@abuzareal/contour-ui/theme-bootstrap` into the HTML head at build time. It has no user-supplied interpolation. A strict Content Security Policy needs the appropriate script hash or nonce; do not enable unsafe inline scripts generally.
101
+ ## Components
70
102
 
71
- Set `data-motion="off"` on your application wrapper when animation is disabled. `useMotionPreference()` tracks the system setting; combine it with your app's pause state. Pass the resulting `motionEnabled` to Three.js scenes and `animate` to theme controls. Reduced motion overrides theme reveal animations even if `animate` is true. No animation is required to operate the UI.
103
+ | Area | Public exports |
104
+ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
105
+ | Actions | `Button`, `IconButton`, `ExternalLink`, `SegmentedControl`, `ThemeToggle` |
106
+ | Forms | `Field`, `TextField`, `TextArea`, `SelectField`, `Checkbox`, `RadioGroup`, `Switch`, `Slider` |
107
+ | Navigation | `Tabs`, `Breadcrumbs`, `Pagination`, `Stepper`, `DropdownMenu` |
108
+ | Data and layout | `Avatar`, `Badge`, `Card`, `DataTable`, `Disclosure`, `Divider`, `EmptyState`, `Kbd`, `SectionLabel`, `Stat`, `Tag`, `Timeline` |
109
+ | Feedback | `Alert`, `ProgressBar`, `Skeleton`, `Spinner`, `ToastProvider`, `useToast` |
110
+ | Motion and identity | `BrandMark`, `CountUp`, `DepthButton`, `FlipCard`, `Magnetic`, `Marquee`, `Reveal`, `RevealHeading`, `ScrollProgress`, `TiltCard`, `GitHubIcon`, `LinkedInIcon` |
111
+ | Overlays and scene fallback | `Dialog`, `Popover`, `Tooltip`, `SceneBoundary` |
72
112
 
73
- `useToast()` must run below `ToastProvider`. The library does not send messages, collect analytics, fetch application data, or require a service account. Links reject executable URL schemes; application authentication, validation, authorization, and data handling remain the application's responsibility.
113
+ The root entry also exports theme, motion, clipboard, dismissal, navigation, and browser-lifecycle hooks plus utility functions. Check `src/index.ts` in a source checkout or `dist/index.d.ts` in the installed package for the complete API. Component declarations describe their props.
74
114
 
75
- ## Optional entries
115
+ Use visible field labels, accessible names for icon buttons, and text alongside status colors. `DataTable` sorts scalar string/number values; `Pagination` expects a positive integer page count and a page within that range. Flip cards use a button and make the hidden face inert.
116
+
117
+ Props support varies between components. Don't assume every export forwards DOM refs, accepts arbitrary native attributes, supports router `asChild` composition, or integrates with form libraries through refs. Verify the relevant type before adopting it.
118
+
119
+ ## Optional scenes and scrolling
120
+
121
+ Core imports don't load Three.js or Lenis. Install either only if you use its entry:
76
122
 
77
123
  ```sh
78
- npm install three@^0.186.1 # only for the /three entry
79
- npm install lenis@^1.3.26 # only for the /scroll entry
124
+ npm install three@^0.186.1 # @abuzareal/contour-ui/three
125
+ npm install lenis@^1.3.26 # @abuzareal/contour-ui/scroll
126
+ # TypeScript consumers of /three also need the matching declarations:
127
+ npm install -D @types/three@^0.186.0
80
128
  ```
81
129
 
130
+ `/scroll` exports `useSmoothScroll`. `/three` exports `Sculpture`, `ObjectStudy`, `useThreeStage`, geometry/material helpers, and associated types. CSS depth controls such as `TiltCard` and `FlipCard` are core exports and don't require Three.js.
131
+
82
132
  ```tsx
83
133
  import { lazy, Suspense } from "react";
134
+ import { SceneBoundary } from "@abuzareal/contour-ui";
135
+
84
136
  const Sculpture = lazy(() =>
85
137
  import("@abuzareal/contour-ui/three").then((module) => ({
86
138
  default: module.Sculpture,
87
139
  })),
88
140
  );
89
141
 
90
- // Provide a sized container and an application-owned static fallback.
91
- <Suspense fallback={<p>Loading preview…</p>}>
92
- <Sculpture motionEnabled={false} />
93
- </Suspense>;
142
+ export function Preview() {
143
+ return (
144
+ <div>
145
+ <p>Three interlocking links, shown in a WebGL preview when available.</p>
146
+ <SceneBoundary>
147
+ <Suspense fallback={<p>Loading preview…</p>}>
148
+ <Sculpture motionEnabled={false} />
149
+ </Suspense>
150
+ </SceneBoundary>
151
+ </div>
152
+ );
153
+ }
94
154
  ```
95
155
 
96
- `/three` also exports `ObjectStudy`, `useThreeStage`, geometry/material helpers, and their types. Treat the 3D API as experimental in this initial release. Scene setup functions are captured on mount; remount the scene when its setup configuration changes. Scenes require WebGL and should always have a visible fallback. No Three.js or Lenis imports occur in the core runtime graph.
97
-
98
- ## Components and typed APIs
156
+ Give scenes a sized container and a usable static fallback. `SceneBoundary` hides a scene on failure; it doesn't supply fallback content, so keep that content outside the boundary. The 3D API is experimental. Stage setup functions are captured on mount; remount a scene when its setup configuration changes. WebGL availability is a runtime requirement for scenes.
99
157
 
100
- The package exports named components and props types. TypeScript declarations are shipped with every entry; editors provide the complete props API.
158
+ ## Release notes and upgrades
101
159
 
102
- - Actions: `Button`, `IconButton`, `ExternalLink`, `SegmentedControl`, `ThemeToggle`.
103
- - Forms: `Field`, `TextField`, `TextArea`, `SelectField`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`.
104
- - Navigation: `Tabs`, `Breadcrumbs`, `Pagination`, `Stepper`, `DropdownMenu`.
105
- - Data and layout: `Avatar`, `Badge`, `Card`, `DataTable`, `Disclosure`, `Divider`, `EmptyState`, `Kbd`, `SectionLabel`, `Stat`, `Tag`, `Timeline`.
106
- - Feedback: `Alert`, `ProgressBar`, `Skeleton`, `Spinner`, `ToastProvider`, `useToast`.
107
- - Motion and signature: `BrandMark`, `CountUp`, `DepthButton`, `FlipCard`, `Magnetic`, `Marquee`, `Reveal`, `RevealHeading`, `ScrollProgress`, `TiltCard`, `GitHubIcon`, `LinkedInIcon`.
108
- - Overlays: `Dialog`, `Popover`, `Tooltip`, `SceneBoundary`.
109
-
110
- `Dialog` locks document scrolling while open, including drawer placements. Its content remains scrollable on short screens. Nested dialogs share the lock; closing or unmounting the last restores the document's previous styles. This behavior is included in version 0.1.1.
111
-
112
- Use visible labels for fields, concise action labels for buttons, accessible labels for icon-only controls, and text alongside status colors. Sortable tables expect scalar string/number row values. Pagination expects a positive integer page count and a page in that range. Flip cards switch through their button; the hidden side is inert.
113
-
114
- Global colors, fonts, radii, duration, and spacing variables are in `tokens.css`. Override semantic tokens rather than copying components into your app. `styles.css` includes tokens and component styles; `fonts.css` and `reset.css` are separately opt-in. Do not import catalogue or portfolio CSS into other apps.
115
-
116
- ## Independent repositories and updates
117
-
118
- This repository contains only the library. The catalogue and portfolio remain separate repositories and consume the same published npm version. During first-release validation, a packed archive can be installed locally; replace the archive dependency with the registry version before committing consumer manifests.
160
+ **0.1.2** adds the optional `fonts-latin.css` export, clearer setup documentation, and links to the Contour UI documentation site. Component APIs and runtime dependencies remain unchanged from 0.1.1. React 19 support and the interaction fixes from 0.1.1 are retained. `CHANGELOG.md` is included in the package archive and [npm's Code view](https://www.npmjs.com/package/@abuzareal/contour-ui?activeTab=code); it contains the upgrade details for each version.
119
161
 
120
162
  ```sh
121
- npm install @abuzareal/contour-ui@0.1.1 --save-exact
163
+ npm install @abuzareal/contour-ui@0.1.2 --save-exact
122
164
  ```
123
165
 
124
- Commit both `package.json` and `package-lock.json`. Dependabot proposes version updates in each consumer repository. Updates reach production after that project's checks, merge, rebuild, and deployment. A registry release does not change deployed applications automatically.
166
+ Commit your manifest and lockfile, run your application's checks, and review both themes, dialogs, forms, and motion before deploying. Version 0.1.1 includes a document scroll lock for dialogs and drawers. Review any app-level lock before removing it, including nested dialogs and short screens. Package publication doesn't update deployed consumers automatically.
167
+
168
+ The package is public under MIT. The source repository and its issue tracker currently require collaborator access. Public users can inspect the distributed code, CSS, declarations, and release documents through npm. Contact the [maintainer](https://github.com/abuzareal) for support; see `SECURITY.md` in the package for vulnerability reporting guidance.
125
169
 
126
- ## Development and release
170
+ ## Develop this library
171
+
172
+ From a source checkout:
127
173
 
128
174
  ```sh
129
175
  npm ci --ignore-scripts
130
- npx playwright install chromium # first browser-test run
176
+ npx playwright install chromium
131
177
  npm run validate
132
- npm run test:compat # packed consumers in both React majors and source compilation with React 19 types
178
+ npm run test:compat
133
179
  npm audit
134
180
  npm pack --dry-run
135
181
  ```
136
182
 
137
- See `RELEASING.md` for the release checklist, authentication, and trusted-publishing setup. The package ships only built code/styles and release documents, with no consumer installation scripts. The complete-source Git repository contains tests and tooling; those are excluded from the npm archive.
183
+ `validate` checks types, lint, builds, Node/component tests, dialog browser behavior, and archive contents. `test:compat` builds packed React 18/19 consumers and compiles the source with React 19 types. `test:consumer` checks one packed consumer, with optional peers absent. `test:optional` verifies strict `/three` and `/scroll` declarations and builds their imports with explicit peers and Three.js types. The compatibility gate runs both checks and verifies the Latin font assets. Compatibility runs need registry access for clean installs.
184
+
185
+ `src/` owns components, hooks, helpers, and public entries. `styles/` owns CSS. `tests/` owns regressions and browser checks; `scripts/` owns builds and package/consumer checks. `dist/` is generated. `RELEASING.md` in the source checkout and package archive covers validation and publication.
138
186
 
139
- MIT licensed. Font dependencies retain their own font licenses; Lucide, React, Three.js, and Lenis retain their respective licenses.
187
+ MIT licensed. Fontsource fonts and dependencies retain their own licenses.
package/RELEASING.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # Releasing Contour UI
2
2
 
3
+ ## Package-page documentation and release notes
4
+
5
+ The npm Readme tab renders the root `README.md`. npm updates it when a new package version is published; editing this repository does not update the existing npm page. Follow [npm's README update guidance](https://docs.npmjs.com/about-package-readme-files/). Do not try to overwrite a published version or unpublish it to change documentation.
6
+
7
+ Keep installation, a working example, CSS/theme setup, supported APIs, optional dependencies, limits, and a release summary in the README. Keep the detailed version history in `CHANGELOG.md`, which ships in the archive and is available through npm's Code view. The private GitHub repository is not a public documentation destination. When public docs and changelog routes exist, add their verified URLs to the README and package metadata.
8
+
9
+ Write new changes under **Unreleased**, or under a version heading explicitly marked **Pending release** when the next version has been chosen. At publication, remove the pending label and record the verified publication date. Use sections only when they contain useful changes: Added, Fixes, Compatibility, Upgrading, and Known limitations. Each entry should name the affected component/API and describe the user's resulting behavior. Include a migration example for incompatible changes. For a documentation-only patch, state that runtime behavior and dependency contracts are unchanged.
10
+
11
+ Link each release to available evidence: changed APIs, relevant tests, and public issues/PRs when readers can access them. Do not invent dates, issue numbers, performance gains, accessibility certification, or compatibility results. Confirm that README examples use the exports and props in the release archive. Run the same release gates for a documentation patch; the archive, manifest, tag, changelog, and registry version must agree. Publishing still requires the maintainer's authorization.
12
+
3
13
  ## Initial release
4
14
 
5
15
  1. Verify `npm whoami` is `abuzareal`; the package is `@abuzareal/contour-ui` and public under MIT.
@@ -32,6 +42,8 @@ Increment PATCH for compatible fixes, MINOR for compatible additions, and MAJOR
32
42
 
33
43
  Dependabot is selected because it is integrated with GitHub and requires no extra hosted service or bot account. It proposes weekly npm and action updates; the library is not auto-merged. npm distribution is public. Standard-hosted Actions run only if the repository is public; checks run locally while it stays private. Do not enable paid runners, private npm distribution, or paid security subscriptions as part of this setup.
34
44
 
35
- The validation workflows deliberately skip private repositories. If a consumer stays private, run its checks locally before merging dependency updates. Enabling private-repository Actions later requires reviewing that account's included usage and spending settings first.
45
+ The library's validation workflows deliberately skip private repositories. Consumer policies vary: Portfolio allows private pull requests to opt in with the `run-validation` label. Check each consumer's workflow and run its required checks locally when CI is skipped. Enabling private-repository Actions requires reviewing that account's included usage and spending settings first.
46
+
47
+ Consumers install with `npm install @abuzareal/contour-ui@VERSION --save-exact`, commit their lockfile, run their checks, and redeploy. Portfolio, Design-System, Atmos, Orbit, and the library remain independent repositories.
36
48
 
37
- Consumers install with `npm install @abuzareal/contour-ui@VERSION --save-exact`, commit their lockfile, run their checks, and redeploy. Keep the three Git repositories independent.
49
+ The compatibility gate also installs the optional Three.js and Lenis peers in separate packed consumers. It checks `/three` and `/scroll` with `skipLibCheck: false`, builds their imports, and verifies the Latin WOFF2 export. Core consumers continue to run without those optional peers. Run `npm run test:optional` for that focused check.
package/dist/fonts-latin.css ADDED
@@ -0,0 +1,35 @@
1
+ /* Optional Latin-only WOFF2 fonts. Use fonts.css for the complete character sets. */
2
+ @font-face {
3
+ font-family: "DM Sans Variable";
4
+ font-style: normal;
5
+ font-display: swap;
6
+ font-weight: 100 1000;
7
+ src: url(@fontsource-variable/dm-sans/files/dm-sans-latin-wght-normal.woff2)
8
+ format("woff2-variations");
9
+ unicode-range:
10
+ U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC,
11
+ U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212,
12
+ U+2215, U+FEFF, U+FFFD;
13
+ }
14
+
15
+ @font-face {
16
+ font-family: "Space Grotesk Variable";
17
+ font-style: normal;
18
+ font-display: swap;
19
+ font-weight: 300 700;
20
+ src: url(@fontsource-variable/space-grotesk/files/space-grotesk-latin-wght-normal.woff2)
21
+ format("woff2-variations");
22
+ unicode-range:
23
+ U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC,
24
+ U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212,
25
+ U+2215, U+FEFF, U+FFFD;
26
+ }
27
+
28
+ @font-face {
29
+ font-family: "DM Mono";
30
+ font-style: normal;
31
+ font-display: swap;
32
+ font-weight: 400;
33
+ src: url(@fontsource/dm-mono/files/dm-mono-latin-400-normal.woff2)
34
+ format("woff2");
35
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@abuzareal/contour-ui",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "private": false,
5
5
  "description": "Editorial React components, themes, restrained motion, and optional Three.js objects.",
6
6
  "type": "module",
@@ -35,7 +35,8 @@
35
35
  "./styles.css": "./dist/styles.css",
36
36
  "./reset.css": "./dist/reset.css",
37
37
  "./tokens.css": "./dist/tokens.css",
38
- "./fonts.css": "./dist/fonts.css"
38
+ "./fonts.css": "./dist/fonts.css",
39
+ "./fonts-latin.css": "./dist/fonts-latin.css"
39
40
  },
40
41
  "scripts": {
41
42
  "build": "node scripts/build.mjs",
@@ -47,7 +48,8 @@
47
48
  "validate": "npm run typecheck && npm run lint && npm run build && npm test && npm run test:browser && npm run check:package",
48
49
  "prepublishOnly": "npm run validate && npm run test:compat",
49
50
  "test:consumer": "node scripts/test-consumer.mjs",
50
- "test:compat": "node scripts/test-compat.mjs"
51
+ "test:compat": "node scripts/test-compat.mjs",
52
+ "test:optional": "node scripts/test-optional-consumer.mjs"
51
53
  },
52
54
  "dependencies": {
53
55
  "@fontsource-variable/dm-sans": "^5.3.0",
@@ -72,7 +74,6 @@
72
74
  "devDependencies": {
73
75
  "@playwright/test": "1.63.0",
74
76
  "@testing-library/react": "^16.3.3",
75
- "@types/node": "^24.13.3",
76
77
  "@types/react": "^18.3.5",
77
78
  "@types/react-dom": "^18.3.0",
78
79
  "@types/three": "^0.186.0",
@@ -97,8 +98,15 @@
97
98
  "type": "git",
98
99
  "url": "git+https://github.com/abuzareal/contour-ui.git"
99
100
  },
100
- "homepage": "https://github.com/abuzareal/contour-ui#readme",
101
+ "homepage": "https://contour.abuzr.in/",
101
102
  "bugs": {
102
103
  "url": "https://github.com/abuzareal/contour-ui/issues"
103
- }
104
+ },
105
+ "keywords": [
106
+ "react",
107
+ "typescript",
108
+ "components",
109
+ "design-system",
110
+ "contour-ui"
111
+ ]
104
112
  }