twico-ui 0.1.0

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 (14) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +182 -0
  3. package/dist/index.cjs +7675 -0
  4. package/dist/index.cjs.map +1 -0
  5. package/dist/index.d.cts +1501 -0
  6. package/dist/index.d.ts +1501 -0
  7. package/dist/index.mjs +7617 -0
  8. package/dist/index.mjs.map +1 -0
  9. package/package.json +71 -0
  10. package/styles/fonts/JetBrainsMono-Variable.ttf +0 -0
  11. package/styles/fonts/OFL-PlusJakartaSans.txt +93 -0
  12. package/styles/fonts/PlusJakartaSans-Italic-Variable.ttf +0 -0
  13. package/styles/fonts/PlusJakartaSans-Variable.ttf +0 -0
  14. package/styles/twico-ui.css +546 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Twico UI
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,182 @@
1
+ # Twico UI
2
+
3
+ A **free**, modern, themeable **React** component library — 53 components with **dark mode**, motion, and accessibility built in. No runtime CSS framework required: components are styled with CSS custom properties (design tokens), so they theme by overriding variables and work great alongside Tailwind or plain CSS.
4
+
5
+ ```bash
6
+ npm install twico-ui
7
+ ```
8
+
9
+ > Requires **React 18+** (`react` and `react-dom` are peer dependencies).
10
+
11
+ ## Framework setup
12
+
13
+ Twico UI works in any React 18+ app. Every component ships with a `"use client"` boundary, so it drops straight into **Next.js App Router** Server Components without extra wrapping.
14
+
15
+ ### React (Vite / CRA)
16
+
17
+ Import the stylesheet once at your entry, then use components anywhere:
18
+
19
+ ```jsx
20
+ // main.jsx
21
+ import "twico-ui/styles.css";
22
+ ```
23
+
24
+ ```jsx
25
+ // App.jsx
26
+ import { Button, Datatable } from "twico-ui";
27
+ ```
28
+
29
+ ### Next.js — App Router (`app/`)
30
+
31
+ Import the CSS once in the root layout. Components can be used directly in Server **or** Client Components (they self-mark as client):
32
+
33
+ ```tsx
34
+ // app/layout.tsx
35
+ import "twico-ui/styles.css";
36
+
37
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
38
+ return (
39
+ <html lang="en">
40
+ <body>{children}</body>
41
+ </html>
42
+ );
43
+ }
44
+ ```
45
+
46
+ ```tsx
47
+ // app/page.tsx (a Server Component — no "use client" needed)
48
+ import { Stat, Button } from "twico-ui";
49
+
50
+ export default function Page() {
51
+ return (
52
+ <main>
53
+ <Stat label="Revenue" value="$48,200" delta="+12.5%" />
54
+ <Button>Get started</Button>
55
+ </main>
56
+ );
57
+ }
58
+ ```
59
+
60
+ For dark mode in the App Router, toggle the class on `<html>` from a Client Component (e.g. a theme button) or set it server-side via the `className` on `<html>`.
61
+
62
+ ### Next.js — Pages Router (`pages/`)
63
+
64
+ Import the CSS once in the custom `_app`:
65
+
66
+ ```tsx
67
+ // pages/_app.tsx
68
+ import "twico-ui/styles.css";
69
+ import type { AppProps } from "next/app";
70
+
71
+ export default function App({ Component, pageProps }: AppProps) {
72
+ return <Component {...pageProps} />;
73
+ }
74
+ ```
75
+
76
+ ### SSR / hydration notes
77
+
78
+ - Components are **SSR-safe** — nothing touches `window`/`document` during render; all browser access is inside effects and event handlers.
79
+ - The global stylesheet (`twico-ui/styles.css`) provides the design tokens, base reset, and self-hosted fonts at first paint. Each component also injects its own scoped CSS on mount, so styles settle immediately after hydration.
80
+ - Overlays (Menu, Popover, Select, CommandPalette, Drawer, Dialog) render through React **portals** to `document.body` only while open, so they never run on the server.
81
+
82
+ ## Quick start
83
+
84
+ Import the stylesheet **once** at your app root, then use any component:
85
+
86
+ ```jsx
87
+ import "twico-ui/styles.css";
88
+ import { Button, Datatable, Input, Switch } from "twico-ui";
89
+
90
+ export default function App() {
91
+ return (
92
+ <div style={{ padding: 24 }}>
93
+ <Input label="Email" placeholder="you@example.com" />
94
+ <Button>Save changes</Button>
95
+
96
+ <Datatable
97
+ rows={[
98
+ { id: 1, name: "Jane Cooper", role: "Admin", mrr: 480 },
99
+ { id: 2, name: "Wade Warren", role: "Editor", mrr: 48 },
100
+ ]}
101
+ rowKey={(r) => r.id}
102
+ columns={[
103
+ { field: "name", headerName: "Member", width: 200 },
104
+ { field: "role", headerName: "Role", valueOptions: ["Admin", "Editor"] },
105
+ { field: "mrr", headerName: "MRR", type: "number", valueFormatter: (v) => `$${v}` },
106
+ ]}
107
+ />
108
+ </div>
109
+ );
110
+ }
111
+ ```
112
+
113
+ ## Dark mode
114
+
115
+ Dark tokens live on the document root. Add `class="dark"` (or `data-theme="dark"`) to `<html>`:
116
+
117
+ ```js
118
+ document.documentElement.classList.toggle("dark");
119
+ ```
120
+
121
+ Everything — including portaled menus, popovers, and the command palette — re-themes together.
122
+
123
+ ## Theming
124
+
125
+ All visuals derive from CSS custom properties. Override them in your own CSS to rebrand without touching components:
126
+
127
+ ```css
128
+ :root {
129
+ --color-primary: #7c3aed; /* brand color */
130
+ --radius-md: 10px; /* corner radius */
131
+ --font-sans: "Inter", sans-serif;/* typeface */
132
+ }
133
+ ```
134
+
135
+ See `styles/twico-ui.css` for the full token set (colors, typography, spacing, radius, motion). The bundled stylesheet also self-hosts the default fonts (Plus Jakarta Sans + JetBrains Mono, OFL) under `twico-ui/styles/fonts/`.
136
+
137
+ ## Components
138
+
139
+ **Buttons & actions:** Button, IconButton
140
+ **Inputs:** Input, Textarea, Currency, CurrencyField, Select, MultiSelect, Combobox, Checkbox, Radio, Switch, Slider, Rating, FileUpload, DatePicker, DateRangePicker, ColorPicker
141
+ **Data display:** Card, Avatar, AvatarMenu, Badge, Tag, Stat, List, Timeline, Chart, Table, Pagination, Datatable, Kanban
142
+ **Navigation:** Tabs, Accordion, Breadcrumb, Stepper, Navbar, Sidebar, TreeView
143
+ **Overlay:** Tooltip, Popover, Menu, Dialog, Drawer, CommandPalette
144
+ **Feedback:** Alert, Spinner, Progress, Skeleton, Toast (+ ToastViewport), EmptyState, Divider, Carousel
145
+
146
+ Every component ships full TypeScript types (e.g. `import type { DatatableProps } from "twico-ui"`).
147
+
148
+ ## Building & publishing (maintainers)
149
+
150
+ This repo is both the Twico UI **design system** and the source of the npm package. The published package contains only the built output (`dist/` + `styles/`).
151
+
152
+ ```bash
153
+ npm install # install build tooling (tsup, typescript)
154
+ npm run build # bundle src/index.ts -> dist (ESM + CJS + .d.ts)
155
+ npm publish # prepublishOnly runs the build automatically
156
+ ```
157
+
158
+ - `src/index.ts` is an auto-generated barrel that re-exports every component from `components/`.
159
+ - `tsup` bundles the JSX to `dist/index.mjs` / `dist/index.cjs` and rolls the hand-written `.d.ts` props contracts into `dist/index.d.ts`.
160
+ - A post-build step (`scripts/add-use-client.mjs`) prepends the `"use client"` directive to the bundles (a tsup `banner` is stripped by esbuild), so the package imports cleanly into Next.js App Router Server Components.
161
+ - `react` / `react-dom` stay external (peer deps).
162
+
163
+ See [`DESIGN-SYSTEM.md`](./DESIGN-SYSTEM.md) for the full design guide (tokens, voice, visual foundations, iconography).
164
+
165
+ ### Branching & releases
166
+
167
+ Twico UI follows **[semantic versioning](https://semver.org/)** (`MAJOR.MINOR.PATCH`):
168
+
169
+ - **`dev`** — the integration branch. All day-to-day work happens here or on `feat/*` / `fix/*` branches that merge into it. Every push and PR runs **CI** (`.github/workflows/ci.yml`): type-check, build, and an assertion that the `"use client"` banner survived bundling.
170
+ - **`main`** — the release branch. It is the **only** branch wired to publish (`.github/workflows/publish.yml`). Merging `dev → main` triggers a release.
171
+
172
+ To cut a release:
173
+
174
+ 1. On `dev`, bump the version in `package.json` per semver (`patch` = fixes, `minor` = new components/props, `major` = breaking changes).
175
+ 2. Open a PR from `dev` into `main` and merge it.
176
+ 3. The publish workflow builds, publishes to npm with provenance, and tags the commit `vX.Y.Z`. It is **idempotent** — if `package.json`'s version is already on npm, the publish step is skipped, so an accidental merge without a version bump never errors.
177
+
178
+ > Publishing requires an `NPM_TOKEN` repository secret (an npm automation token with publish rights).
179
+
180
+ ## License
181
+
182
+ MIT © Twico UI. Free for any use — personal or commercial.