night-city-ui 0.1.0 → 0.1.1

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 (2) hide show
  1. package/README.md +13 -340
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -7,37 +7,9 @@
7
7
  [![React 18+](https://img.shields.io/badge/React-%E2%89%A518-61dafb.svg)](https://react.dev)
8
8
  [![Types included](https://img.shields.io/badge/TypeScript-types%20included-3178c6.svg)](https://www.typescriptlang.org)
9
9
 
10
- A React + TypeScript component kit inspired by the four design languages of Cyberpunk 2077: **Scrap//Tech**, **Tacky//Futurism**, **Corpo//Brutalism** and **Hyper//Opulence**.
10
+ React + TypeScript component kit with four switchable skins: **Scrap//Tech**, **Tacky//Futurism**, **Corpo//Brutalism** and **Hyper//Opulence**. Semantic markup, CSS custom properties, no runtime dependencies beyond React.
11
11
 
12
- One component contract, four skins, zero UI dependencies. Every component is semantic markup plus CSS custom properties, so a theme changes color, type, radius, borders, shadows and texture without touching structure.
13
-
14
- > 📖 **Guía en español:** [GUIA_DE_USO.md](./GUIA_DE_USO.md) — integración, temas y recetas de color.
15
-
16
- - **Live demo:** https://dan-netrunner.github.io/night-city-ui/
17
- - **Repository:** https://github.com/dan-netrunner/night-city-ui
18
- - **npm:** `npm install night-city-ui`
19
- - **License:** [MIT](./LICENSE) — free for personal and commercial use.
20
-
21
- ---
22
-
23
- ## Features
24
-
25
- - **4 live themes** driven by `data-theme` and CSS custom properties.
26
- - **28 exported components** plus styled tables and documentation layout helpers.
27
- - **Accessible defaults:** native controls, visible focus rings, ARIA tabs, a real `<dialog>`, keyboard-operable accordions and tooltips.
28
- - **No runtime dependencies** beyond React and React DOM.
29
- - **ESM + TypeScript types** built for bundlers, with the stylesheet shipped as `night-city-ui/style.css`.
30
- - **Interactive docs:** component workbench, live color lab, theme comparison and a full operator dashboard playground.
31
- - **GitHub Pages ready** with relative asset paths and a deploy workflow.
32
-
33
- ---
34
-
35
- ## Requirements
36
-
37
- - React 18 or newer (peer dependency; the docs site is built with React 19)
38
- - Node.js 20 or newer and npm 10 or newer, only to run or build this repository
39
-
40
- ---
12
+ **Docs:** [Overview](https://dan-netrunner.github.io/night-city-ui/) · [Components](https://dan-netrunner.github.io/night-city-ui/#/components) · [Guide](https://dan-netrunner.github.io/night-city-ui/#/guide) · [Guía ES](./GUIA_DE_USO.md) · [npm](https://www.npmjs.com/package/night-city-ui)
41
13
 
42
14
  ## Install
43
15
 
@@ -45,329 +17,30 @@ One component contract, four skins, zero UI dependencies. Every component is sem
45
17
  npm install night-city-ui
46
18
  ```
47
19
 
48
- Then import the stylesheet once, and components anywhere:
49
-
50
20
  ```tsx
51
21
  import "night-city-ui/style.css";
52
22
  import { Button, Panel, ThemeProvider } from "night-city-ui";
53
23
  ```
54
24
 
55
- `night-city-ui` ships ESM (`dist/night-city-ui.js`) and TypeScript declarations (`dist/index.d.ts`). It does not bundle fonts — see [Fonts](#fonts).
56
-
57
- ---
25
+ React ≥18. No font files are bundled — the CSS falls back to system fonts. For the intended look install the `@fontsource` families you want (see the Guide).
58
26
 
59
- ## Run the docs site locally
27
+ ## Development
60
28
 
61
29
  ```bash
62
- git clone git@github.com:dan-netrunner/night-city-ui.git
63
- cd night-city-ui
64
30
  npm install
65
- npm run dev
66
- ```
67
-
68
- The dev server prints a local URL (Vite default: `http://localhost:5173`). Other scripts:
69
-
70
- ```bash
71
- npm run build # type-check with tsc and build the docs site into dist/
72
- npm run build:lib # build the npm package (bundle + types) into dist/
73
- npm run preview # serve the production build locally
74
- ```
75
-
76
-
77
- ---
78
-
79
- ## Minimal setup
80
-
81
- ```tsx
82
- import "night-city-ui/style.css";
83
- import { Badge, Button, Panel, Progress, ThemeProvider } from "night-city-ui";
84
-
85
- export function App() {
86
- return (
87
- <ThemeProvider>
88
- <Panel
89
- kicker="// SYS.01"
90
- title="Terminal"
91
- telemetry="LINK: OK"
92
- accent
93
- >
94
- <Badge tone="ok" pulse>
95
- Online
96
- </Badge>
97
- <Progress label="RAM deck" value={75} segmented />
98
- <Button code="01">Engage</Button>
99
- </Panel>
100
- </ThemeProvider>
101
- );
102
- }
103
- ```
104
-
105
- `ThemeProvider` writes `data-theme` on `<html>`, persists the choice in `localStorage` (`nc-theme`) and applies the saved theme before first paint to avoid a flash.
106
-
107
- ### Fonts
108
-
109
- The stylesheet references these families, with system fallbacks:
110
-
111
- | Token | Family |
112
- | --- | --- |
113
- | `--font-display` / `--font-ui` / `--font-body` | Rajdhani, Orbitron, Bungee, Bebas Neue (per theme) |
114
- | `--font-mono` | Share Tech Mono |
115
-
116
- The kit does not bundle the font files. For the intended look, add the ones you need — this is exactly what the docs site does:
117
-
118
- ```bash
119
- npm install @fontsource/rajdhani @fontsource/bebas-neue @fontsource/bungee @fontsource/orbitron @fontsource/share-tech-mono
120
- ```
121
-
122
- ```ts
123
- import "@fontsource/rajdhani/400.css";
124
- import "@fontsource/rajdhani/500.css";
125
- import "@fontsource/rajdhani/600.css";
126
- import "@fontsource/rajdhani/700.css";
127
- import "@fontsource/bebas-neue/400.css";
128
- import "@fontsource/bungee/400.css";
129
- import "@fontsource/orbitron/500.css";
130
- import "@fontsource/orbitron/700.css";
131
- import "@fontsource/share-tech-mono/400.css";
132
- ```
133
-
134
- Without them the components still work and fall back to the system sans/mono stack.
135
-
136
- ---
137
-
138
- ## Theming
139
-
140
- ### Switch skins globally
141
-
142
- ```tsx
143
- import { useTheme } from "night-city-ui";
144
-
145
- function ThemeMenu() {
146
- const { theme, setTheme, meta } = useTheme();
147
- return (
148
- <button onClick={() => setTheme("kitsch")}>
149
- {meta.name} → Tacky//Futurism
150
- </button>
151
- );
152
- }
153
- ```
154
-
155
- Available ids (used in `data-theme`): `neokitsch` (Hyper//Opulence, default), `entropism` (Scrap//Tech), `kitsch` (Tacky//Futurism), `neomilitarism` (Corpo//Brutalism).
156
-
157
- ### Scope a skin to a subtree
158
-
159
- `data-theme` is a plain attribute, so any section can run a different skin:
160
-
161
- ```tsx
162
- <section data-theme="neomilitarism">
163
- <Panel title="Tactical HUD">
164
- <Button>Deploy</Button>
165
- </Panel>
166
- </section>
167
- ```
168
-
169
- ### Create a custom theme
170
-
171
- All components read variables from the bundled `tokens.css`. Override the ones you need:
172
-
173
- ```css
174
- [data-theme="custom"] {
175
- --accent: #00f0ff;
176
- --accent-2: #fcee0a;
177
- --accent-ink: #041214;
178
- --accent-ghost: color-mix(in oklch, #00f0ff 14%, transparent);
179
- --panel: #121a2c;
180
- --glow: 0 0 18px color-mix(in oklch, #00f0ff 32%, transparent);
181
- }
182
- ```
183
-
184
- | Token | Role |
185
- | --- | --- |
186
- | `--bg`, `--bg-2` | Viewport background |
187
- | `--panel`, `--panel-2` | Panels, cards, modals |
188
- | `--ink`, `--ink-dim`, `--ink-faint` | Primary, secondary and micro-label text |
189
- | `--line`, `--line-strong` | Base and emphasized borders |
190
- | `--accent`, `--accent-2` | Neon accent and secondary accent |
191
- | `--accent-ink` | Text color on `--accent` fills |
192
- | `--accent-ghost` | Translucent hover/active fill |
193
- | `--ok`, `--warn`, `--danger` (+ `*-ink`) | Semantic states |
194
- | `--glow`, `--focus-glow` | Neon glow and focus ring |
195
- | `--radius*`, `--border-w` | Corner and border treatment |
196
- | `--clip-panel`, `--clip-btn`, `--clip-tab`, `--clip-mark` | Cut-corner silhouettes |
197
- | `--font-display`, `--font-ui`, `--font-body`, `--font-mono` | Type system |
198
- | `--page-bg`, `--bar-bg`, `--noise-opacity` | Page texture, header bar and grain |
199
-
200
- A live color lab on the **Guide** page generates the CSS block for you.
201
-
202
- ---
203
-
204
- ## Components
205
-
206
- Import everything from one entry point:
207
-
208
- ```tsx
209
- import { Button, Panel, ToastStack } from "night-city-ui";
210
- ```
211
-
212
- ### Actions and surfaces
213
-
214
- | Component | Key props |
215
- | --- | --- |
216
- | `Button` | `variant`: `primary` \| `ghost` \| `outline` \| `danger`; `size`: `sm` \| `md` \| `lg`; `block`; `code` (HUD micro-tag) |
217
- | `Panel` | `title`, `kicker`, `actions`, `footer`, `telemetry` (corner stamp), `accent`, `flush` |
218
- | `Divider` | `label` (renders a labeled rule) |
219
- | `EmptyState` | `title`, `children`, `glyph`, `action` |
220
- | `Metric` | `label`, `value`, `unit`, `delta`, `tone`: `accent` \| `ok` \| `warn` \| `danger` |
221
-
222
- ### Forms
223
-
224
- | Component | Key props |
225
- | --- | --- |
226
- | `Input` | `label`, `hint`, `error` + all `<input>` attributes |
227
- | `Textarea` | Same as `Input`, plus `rows` (default `4`) |
228
- | `Select` | `label`, `hint`, `error`; options as children |
229
- | `Checkbox` | `label`, `hint`, `defaultChecked` |
230
- | `Radio` | `label`, `hint`, `name`, `value`; group with the same `name` |
231
- | `Toggle` | `label`, `hint`; renders a switch |
232
- | `Slider` | `label`, `value`, `defaultValue`, `min`, `max`, `suffix`, `onChange` |
233
-
234
- ```tsx
235
- <fieldset>
236
- <Radio name="route" label="Rooftop" defaultChecked />
237
- <Radio name="route" label="Freight elevator" />
238
- </fieldset>
239
- ```
240
-
241
- ### Feedback
242
-
243
- | Component | Key props |
244
- | --- | --- |
245
- | `Alert` | `tone`: `info` \| `ok` \| `warn` \| `danger`; `title`; `onDismiss` |
246
- | `Badge` | `tone`: `neutral` \| `accent` \| `ok` \| `warn` \| `danger`; `solid`; `pulse` |
247
- | `Progress` | `value`, `max`, `label`, `showValue`, `segmented`, `segments`, `tone` |
248
- | `Tooltip` | `label`, `side`: `top` \| `bottom`; child must be focusable |
249
- | `Toast` | `title`, `tone`, `onDismiss` |
250
- | `ToastStack` | `items: ToastItem[]`, `onDismiss(id)`, `label` |
251
- | `Spinner` | `label`, `size`: `sm` \| `md` \| `lg` |
252
- | `Skeleton` | `width`, `height` |
253
-
254
- ```tsx
255
- const [toasts, setToasts] = useState<ToastItem[]>([]);
256
-
257
- <ToastStack
258
- items={toasts}
259
- onDismiss={(id) => setToasts((list) => list.filter((t) => t.id !== id))}
260
- />
261
- ```
262
-
263
- ### Navigation and disclosure
264
-
265
- | Component | Key props |
266
- | --- | --- |
267
- | `Tabs` | `items: { id, label, count? }[]`, `value`, `onChange`, `label` |
268
- | `Accordion` | `items: { id, title, meta?, children }[]`, `defaultOpen` |
269
- | `Breadcrumbs` | `items: { label, href? }[]`, `label` |
270
- | `Pagination` | `page`, `pageCount`, `onChange`, `label` |
271
- | `Modal` | `open`, `onClose`, `title`, `kicker`, `footer` |
272
-
273
- `Tabs` supports arrow-key navigation. `Modal` wraps a native `<dialog>` and gets the focus trap, `Esc` handling and backdrop for free. `Accordion` uses `<details>`/`<summary>` and needs no JavaScript.
274
-
275
- ### Content
276
-
277
- | Component | Key props |
278
- | --- | --- |
279
- | `Avatar` | `name`, `src`, `status`: `online` \| `busy` \| `offline`, `size` |
280
- | `Kbd` | `children` |
281
- | `CodeBlock` | `code`, `label`; includes a copy button |
282
- | `Table` | CSS only: wrap in `.cp-table-wrap` and add `.cp-table` to `<table>` |
283
-
284
- `Avatar` derives initials from `name` when no `src` is given and exposes the full name through `aria-label`.
285
-
286
- ---
287
-
288
- ## Accessibility notes
289
-
290
- - Focus rings use `--focus-glow` and never rely on color alone.
291
- - `Tabs` uses `role="tablist"`/`role="tab"`, roving `tabIndex` and Arrow keys.
292
- - `Tooltip` attaches `aria-describedby` to the trigger; wrap a real control.
293
- - Toasts use `role="status"` (or `role="alert"` for danger) so they are announced.
294
- - `prefers-reduced-motion` disables shimmer, pulse and spin animations.
295
- - Decorative textures, status dots and glyphs are `aria-hidden`.
296
-
297
- ---
298
-
299
- ## Project structure
300
-
31
+ npm run dev # docs site with hot reload
32
+ npm run build # type-check + build the docs site
33
+ npm run build:lib # build the npm package into dist/
34
+ npm run preview # serve the production build
301
35
  ```
302
- src/
303
- components/ # one file per component group + index.ts barrel
304
- pages/ # demo: Overview, Components, Playground, Themes, Guide
305
- styles/
306
- tokens.css # design tokens and the four themes
307
- ui.css # component styles
308
- app.css # demo site layout only
309
- index.ts # package entry: styles + public exports
310
- theme.tsx # ThemeProvider + useTheme
311
- App.tsx # hash router + shell
312
- data.ts # demo data
313
- vite.lib.config.ts # library build (npm package)
314
- tsconfig.lib.json # declaration emit
315
- ```
316
-
317
- Demo pages are not part of the component API; they are only exported by the docs site, never by the package entry.
318
-
319
- ---
320
-
321
- ## Publishing
322
-
323
- ### npm
324
-
325
- `.github/workflows/publish-npm.yml` runs on every push or merge to `main` and with manual dispatch. It installs, runs `npm publish` (which triggers `prepublishOnly` → `npm run build:lib`) and publishes with provenance.
326
-
327
- Setup, once:
328
-
329
- 1. Create the repository secret **`NPM_SECRET`** for the **environment `npm`** (Settings → Environments → `npm` → Environment secrets). Use an npm **automation** token or a granular token with read/write on `night-city-ui`.
330
- 2. Keep `package.json` `name`, `version` and `repository` in sync.
331
-
332
- Then bump the version to ship:
333
-
334
- ```bash
335
- npm version patch # or minor / major
336
- git push # merge to main publishes the new version
337
- ```
338
-
339
- If `package.json` still has a version that already exists on npm, the workflow skips the publish and reports it, so merges without a bump stay green.
340
-
341
- Publishing locally is also possible:
342
-
343
- ```bash
344
- npm login
345
- npm publish --access public
346
- ```
347
-
348
- ### GitHub Pages
349
-
350
- The workflow at `.github/workflows/deploy-pages.yml` builds the docs site into `dist/` with `npm run build` on every push or merge to `main` and force-pushes it to the **`gh-pages`** branch. `base: "./"` in `vite.config.ts` keeps asset paths relative, so the site works from the repository subpath.
351
-
352
- 1. Push the repository to GitHub.
353
- 2. Open **Settings → Pages → Build and deployment**.
354
- 3. Set **Source** to **Deploy from a branch**, branch **`gh-pages`**, folder **`/` (root)**.
355
- 4. Push to `main` (or run the workflow manually from **Actions**). The first run creates `gh-pages`; if the branch is not listed yet, run the workflow once and reload the Pages settings.
356
-
357
- Expected URL: `https://dan-netrunner.github.io/night-city-ui/`.
358
-
359
- The workflow is intentionally triggered by `main`, not by `gh-pages`: the action writes `dist/` to `gh-pages`, so triggering on that branch would redeploy on its own output. `main` stays the source of truth and `gh-pages` is only the published artifact.
360
-
361
- <details>
362
- <summary>Alternative: deploy with a GitHub Actions artifact</summary>
363
36
 
364
- If you prefer not to keep a `gh-pages` branch, replace the workflow with the standard `actions/upload-pages-artifact` + `actions/deploy-pages` pair and set **Settings → Pages → Source** to **GitHub Actions**. In that model `main` is both the source and the deployment trigger, and no branch is written.
365
- </details>
37
+ ## Releasing
366
38
 
367
- ---
39
+ - **Site:** merging to `main` builds and deploys to `gh-pages` → https://dan-netrunner.github.io/night-city-ui/
40
+ - **npm:** merging to `main` publishes `package.json`'s version (skipped when that version already exists). Run `npm version patch|minor|major` before merging to release. Auth is OIDC trusted publishing — no token secret. One-time setup: on npmjs.com → package → Settings → Trusted Publisher, add GitHub Actions with repo `dan-netrunner/night-city-ui`, workflow `publish-npm.yml`, environment `npm`, and allow `npm publish`; then set Publishing access to "Require 2FA and disallow tokens". If the publish still gets staged, approve it with `npm stage list night-city-ui` and `npm stage approve <stage-id>`.
368
41
 
369
42
  ## License
370
43
 
371
- [MIT](./LICENSE). Use it, fork it, sell it — keep the copyright notice.
44
+ [MIT](./LICENSE).
372
45
 
373
- This is an independent fan project. It is not affiliated with or endorsed by CD Projekt Red, and it ships no game assets, logos, characters or fonts owned by them. Cyberpunk 2077 is a trademark of CD Projekt Red.
46
+ Independent fan project. Not affiliated with or endorsed by CD Projekt Red; no game assets, logos or fonts are included. Cyberpunk 2077 is a trademark of CD Projekt Red.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "night-city-ui",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Cyberpunk React component kit with four switchable themes, semantic markup and zero UI dependencies.",
5
5
  "license": "MIT",
6
6
  "type": "module",