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.
- package/README.md +13 -340
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -7,37 +7,9 @@
|
|
|
7
7
|
[](https://react.dev)
|
|
8
8
|
[](https://www.typescriptlang.org)
|
|
9
9
|
|
|
10
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
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).
|
|
44
|
+
[MIT](./LICENSE).
|
|
372
45
|
|
|
373
|
-
|
|
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.
|