@dnotrever2/super-kit 0.1.0

package/README.md

@@ -0,0 +1,666 @@
+# @dnotrever2/super-kit
+
+React component library for the **Verazor** design system. Dark, layered, technical aesthetic built on Geist + Geist Mono. Zero runtime dependencies.
+
+---
+
+## Install
+
+```bash
+npm install @dnotrever2/super-kit
+```
+
+**Peer dependencies** — install if not already present:
+
+```bash
+npm install react react-dom
+```
+
+---
+
+## Setup
+
+Import the global stylesheet once at your app's entry point. It provides all design tokens, base resets, and scrollbar utilities:
+
+```ts
+import "@dnotrever2/super-kit/dist/styles/index.css";
+```
+
+> CSS modules are injected into the JS bundle by Vite — there is no separate `.css` output per component. Only the global stylesheet needs a manual import.
+
+---
+
+## Components
+
+### Badge
+
+Status labels, tags, counts, and version strings.
+
+```tsx
+import { Badge } from "@dnotrever2/super-kit";
+
+<Badge variant="success">Deployed</Badge>
+<Badge variant="danger" pill>Failed</Badge>
+<Badge variant="dot" dotColor="var(--success)">Online</Badge>
+<Badge variant="count">12</Badge>
+<Badge variant="version">v2.4.1</Badge>
+<Badge dismissable onDismiss={() => {}}>api-gateway</Badge>
+```
+
+| Prop          | Type                                                                                                                            | Default         |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| `variant`     | `"neutral" \| "accent" \| "outline" \| "success" \| "warning" \| "danger" \| "info" \| "count" \| "mono" \| "version" \| "dot"` | `"neutral"`     |
+| `icon`        | `ReactNode`                                                                                                                     | —               |
+| `pill`        | `boolean`                                                                                                                       | `false`         |
+| `dismissable` | `boolean`                                                                                                                       | `false`         |
+| `onDismiss`   | `() => void`                                                                                                                    | —               |
+| `dotColor`    | `string`                                                                                                                        | `var(--accent)` |
+
+---
+
+### Button
+
+Standard action button with semantic variants and loading state.
+
+```tsx
+import { Button } from "@dnotrever2/super-kit";
+
+<Button variant="primary" onClick={deploy}>Deploy</Button>
+<Button variant="success" icon={<CheckIcon />}>Approve</Button>
+<Button variant="danger">Delete</Button>
+<Button variant="primary" loading icon={<Spinner size="sm" onAccent />}>
+  Deploying
+</Button>
+```
+
+| Prop       | Type                                                                        | Default       |
+| ---------- | --------------------------------------------------------------------------- | ------------- |
+| `variant`  | `"primary" \| "secondary" \| "ghost" \| "danger" \| "success" \| "warning"` | `"secondary"` |
+| `size`     | `"sm" \| "md" \| "lg"`                                                      | `"md"`        |
+| `icon`     | `ReactNode`                                                                 | —             |
+| `loading`  | `boolean`                                                                   | `false`       |
+| `disabled` | `boolean`                                                                   | `false`       |
+
+Forwards a `ref` to the underlying `<button>`. Accepts all native button attributes.
+
+---
+
+### Card
+
+Container surface with optional tilt hover effect and close button.
+
+```tsx
+import { Card, CardHeader, CardStat } from "@dnotrever2/super-kit";
+
+<Card padding="md" tilt onClose={() => setVisible(false)}>
+  <CardHeader
+    icon={<DatabaseIcon />}
+    title="orders-db"
+    subtitle="postgres · us-east-1"
+  />
+  <CardStat value="2.4" unit="ms" delta="-12%" deltaDirection="positive" />
+</Card>
+```
+
+**Card props**
+
+| Prop            | Type                                      | Default                                                         |
+| --------------- | ----------------------------------------- | --------------------------------------------------------------- |
+| `padding`       | `"none" \| "sm" \| "md" \| "lg"`          | `"md"`                                                          |
+| `tilt`          | `boolean`                                 | `false` — hover lifts the card with a subtle 3D tilt and shadow |
+| `onClose`       | `() => void`                              | — — renders a × button (fades in on hover)                      |
+| `closeBtnProps` | `ButtonHTMLAttributes<HTMLButtonElement>` | —                                                               |
+
+**CardHeader props**
+
+| Prop       | Type                   |
+| ---------- | ---------------------- |
+| `title`    | `ReactNode` (required) |
+| `subtitle` | `ReactNode`            |
+| `icon`     | `ReactNode`            |
+
+**CardStat props**
+
+| Prop             | Type                                    | Default      |
+| ---------------- | --------------------------------------- | ------------ |
+| `value`          | `ReactNode` (required)                  | —            |
+| `unit`           | `string`                                | —            |
+| `delta`          | `string`                                | —            |
+| `deltaDirection` | `"positive" \| "negative" \| "neutral"` | `"positive"` |
+
+---
+
+### Input
+
+Text input with label, icon, mask, and clear button.
+
+```tsx
+import { Input } from "@dnotrever2/super-kit";
+
+// Basic
+<Input label="name" placeholder="api-gateway" clearable />
+
+// With icon
+<Input label="search" icon={<SearchIcon />} placeholder="Search services" />
+
+// With mask — only digits allowed, formatted as 000-0000
+<Input
+  label="code"
+  mask="XXX-XXXX"
+  maskAllowedPattern={/\d/}
+  placeholder="000-0000"
+  onValueChange={({ value, rawValue }) => console.log(rawValue)}
+/>
+
+// Select all on focus, right-aligned text
+<Input selectOnFocus textAlign="right" defaultValue="127.0.0.1" />
+```
+
+**How masks work**
+
+- `mask` — format string where every character is a literal except positions matched by `maskAllowedPattern`. Example: `"(XX) XXXXX-XXXX"` for Brazilian phone numbers.
+- `maskAllowedPattern` — `RegExp` that each typed character must match (default: any character). Use `/\d/` for digits-only, `/[A-Za-z]/` for letters-only.
+- `maskPlaceholder` — character used to fill empty mask positions (e.g. `"_"`). If omitted, empty positions are left blank.
+- `onValueChange` receives both `value` (formatted with mask) and `rawValue` (mask characters stripped).
+
+| Prop                     | Type                                    | Default |
+| ------------------------ | --------------------------------------- | ------- |
+| `label`                  | `string`                                | —       |
+| `icon`                   | `ReactNode`                             | —       |
+| `mask`                   | `string`                                | —       |
+| `maskAllowedPattern`     | `RegExp`                                | —       |
+| `maskPlaceholder`        | `string`                                | —       |
+| `clearable`              | `boolean`                               | `false` |
+| `selectOnFocus`          | `boolean`                               | `false` |
+| `textAlign`              | `"left" \| "center" \| "right"`         | —       |
+| `value` / `defaultValue` | `string`                                | `""`    |
+| `onChange`               | `ChangeEvent<HTMLInputElement>`         | —       |
+| `onValueChange`          | `(change: { value, rawValue }) => void` | —       |
+| `wrapperProps`           | `HTMLAttributes<HTMLSpanElement>`       | —       |
+| `fieldProps`             | `HTMLAttributes<HTMLDivElement>`        | —       |
+
+Forwards a `ref` to the underlying `<input>`.
+
+---
+
+### Markers
+
+Form selection primitives: Checkbox, Radio, and Switch.
+
+```tsx
+import { Checkbox, Radio, RadioGroup, Switch } from "@dnotrever2/super-kit";
+
+<Checkbox label="Auto-deploy" checked={checked} onChange={setChecked} />
+<Checkbox label="Partial" indeterminate />
+<Checkbox label="Disabled" disabled />
+
+<RadioGroup>
+  <Radio label="main → production" value="prod" checked={v === "prod"} onChange={setV} />
+  <Radio label="main → staging" value="staging" checked={v === "staging"} onChange={setV} />
+</RadioGroup>
+
+<Switch label="SSO required" checked={on} onChange={setOn} />
+```
+
+**Checkbox / Switch props**
+
+| Prop             | Type                         |
+| ---------------- | ---------------------------- |
+| `label`          | `ReactNode`                  |
+| `checked`        | `boolean`                    |
+| `defaultChecked` | `boolean`                    |
+| `indeterminate`  | `boolean` (Checkbox only)    |
+| `disabled`       | `boolean`                    |
+| `onChange`       | `(checked: boolean) => void` |
+
+**Radio props**
+
+| Prop       | Type                      |
+| ---------- | ------------------------- |
+| `label`    | `ReactNode`               |
+| `value`    | `string`                  |
+| `checked`  | `boolean`                 |
+| `disabled` | `boolean`                 |
+| `onChange` | `(value: string) => void` |
+
+---
+
+### Menu
+
+Composable dropdown menu — render inside a positioned container toggled by your own trigger button.
+
+```tsx
+import { Menu, MenuItem, MenuSeparator } from "@dnotrever2/super-kit";
+
+const [open, setOpen] = useState(false);
+
+<div style={{ position: "relative", display: "inline-block" }}>
+  <Button onClick={() => setOpen(o => !o)}>Options</Button>
+  {open && (
+    <div style={{ position: "absolute", top: "calc(100% + 4px)", left: 0, zIndex: 20 }}>
+      <Menu style={{ width: 240 }}>
+        <MenuItem icon={<PlayIcon />} kbd="⌘R">Run workflow</MenuItem>
+        <MenuItem icon={<CopyIcon />}>Duplicate</MenuItem>
+        <MenuSeparator />
+        <MenuItem icon={<TrashIcon />} danger>Delete</MenuItem>
+      </Menu>
+    </div>
+  )}
+</div>
+```
+
+**MenuItem props**
+
+| Prop       | Type        | Default                  |
+| ---------- | ----------- | ------------------------ |
+| `icon`     | `ReactNode` | —                        |
+| `kbd`      | `string`    | — keyboard shortcut hint |
+| `active`   | `boolean`   | `false`                  |
+| `danger`   | `boolean`   | `false`                  |
+| `disabled` | `boolean`   | `false`                  |
+
+---
+
+### Modal
+
+Dialog overlay with backdrop. Renders as a `div`-based panel, not `<dialog>`.
+
+```tsx
+import { Modal } from "@dnotrever2/super-kit";
+
+<Modal
+  open={isOpen}
+  title="Confirm delete"
+  onClose={() => setIsOpen(false)}
+>
+  <p>This action cannot be undone.</p>
+</Modal>
+```
+
+| Prop       | Type         | Default |
+| ---------- | ------------ | ------- |
+| `open`     | `boolean`    | `false` |
+| `title`    | `ReactNode`  | —       |
+| `onClose`  | `() => void` | —       |
+| `children` | `ReactNode`  | —       |
+
+---
+
+### Popover
+
+Anchored floating panel, controlled or uncontrolled.
+
+```tsx
+import { Popover } from "@dnotrever2/super-kit";
+
+<Popover
+  trigger={<Button variant="secondary">Settings</Button>}
+  title="Connection"
+  side="bottom-start"
+>
+  <p>Content here</p>
+</Popover>
+```
+
+| Prop              | Type                                                         | Default          |
+| ----------------- | ------------------------------------------------------------ | ---------------- |
+| `trigger`         | `ReactNode`                                                  | —                |
+| `title`           | `ReactNode`                                                  | —                |
+| `side`            | `"bottom-start" \| "bottom-end" \| "top-start" \| "top-end"` | `"bottom-start"` |
+| `open`            | `boolean`                                                    | — (controlled)   |
+| `defaultOpen`     | `boolean`                                                    | `false`          |
+| `showCloseButton` | `boolean`                                                    | `true`           |
+| `onOpenChange`    | `(open: boolean) => void`                                    | —                |
+| `popProps`        | `HTMLAttributes<HTMLDivElement>`                             | —                |
+
+---
+
+### PushButton
+
+Toggle button and grouped toolbar segments.
+
+```tsx
+import { PushButton, PushButtonGroup } from "@dnotrever2/super-kit";
+
+// Standalone toggle
+<PushButton on={active} accent onClick={() => setActive(a => !a)} icon={<GridIcon />} />
+
+// Grouped toolbar
+<PushButtonGroup>
+  <PushButton on={view === "list"} onClick={() => setView("list")}>List</PushButton>
+  <PushButton on={view === "grid"} onClick={() => setView("grid")}>Grid</PushButton>
+</PushButtonGroup>
+```
+
+**PushButton props**
+
+| Prop       | Type        | Default                                       |
+| ---------- | ----------- | --------------------------------------------- |
+| `on`       | `boolean`   | `false`                                       |
+| `accent`   | `boolean`   | `false` — accent color when active            |
+| `solo`     | `boolean`   | `false` — standalone (no group border fusion) |
+| `icon`     | `ReactNode` | —                                             |
+| `disabled` | `boolean`   | `false`                                       |
+
+---
+
+### Scrollable
+
+Scrollable container with custom styled scrollbar.
+
+```tsx
+import { Scrollable } from "@dnotrever2/super-kit";
+
+<Scrollable height={200} track arrows scrollbarSize={8}>
+  {items.map(item => <div key={item}>{item}</div>)}
+</Scrollable>
+```
+
+| Prop            | Type                                   | Default                                              |
+| --------------- | -------------------------------------- | ---------------------------------------------------- |
+| `direction`     | `"vertical" \| "horizontal" \| "both"` | `"vertical"`                                         |
+| `track`         | `boolean`                              | `false` — shows a visible track behind the thumb     |
+| `arrows`        | `boolean`                              | `false` — shows arrow buttons (WebKit only)          |
+| `scrollbarSize` | `number`                               | `10` — scrollbar track width in pixels (WebKit only) |
+| `height`        | `string \| number`                     | —                                                    |
+
+The scrollbar classes (`sb`, `sb-track`, `sb-arrows`) are also available as global CSS classes — apply them directly to any scrollable element.
+
+---
+
+### Select
+
+Single or multi-value dropdown with optional search and clearable state.
+
+```tsx
+import { Select } from "@dnotrever2/super-kit";
+
+const options = [
+  { value: "us-east-1", label: "US East (N. Virginia)" },
+  { value: "eu-west-1", label: "EU West (Ireland)" },
+];
+
+// Single
+<Select label="region" options={options} onValueChange={(v) => setRegion(v)} />
+
+// Multi + searchable
+<Select
+  label="regions"
+  options={options}
+  multiple
+  searchable
+  clearable
+  onValueChange={(values) => setRegions(values)}
+/>
+```
+
+| Prop                     | Type                                   | Default                   |
+| ------------------------ | -------------------------------------- | ------------------------- |
+| `options`                | `{ value, label, meta?, disabled? }[]` | required                  |
+| `value` / `defaultValue` | `string \| string[] \| null`           | `null`                    |
+| `multiple`               | `boolean`                              | `false`                   |
+| `searchable`             | `boolean`                              | `false`                   |
+| `clearable`              | `boolean`                              | `false`                   |
+| `disabled`               | `boolean`                              | `false`                   |
+| `placeholder`            | `string`                               | `"Select"`                |
+| `label`                  | `string`                               | —                         |
+| `onValueChange`          | `(value, selectedOptions) => void`     | —                         |
+| `filterOptions`          | `(options, search) => options`         | built-in case-insensitive |
+| `isLoading`              | `boolean`                              | `false`                   |
+| `loadingLabel`           | `string`                               | `"Loading..."`            |
+| `emptyLabel`             | `string`                               | `"No options found"`      |
+
+Forwards a `ref` to the root `<div>`.
+
+---
+
+### Spinner
+
+Loading indicator in three styles.
+
+```tsx
+import { Spinner } from "@dnotrever2/super-kit";
+
+<Spinner variant="ring" size="md" />
+<Spinner variant="dots" />
+<Spinner variant="bar" />
+
+// Inside a primary button (white on accent background)
+<Button variant="primary" loading icon={<Spinner size="sm" onAccent />}>
+  Deploying
+</Button>
+
+// Subdued — when the accent blue is too visually dominant
+<Spinner muted />
+```
+
+| Prop       | Type                        | Default                                                   |
+| ---------- | --------------------------- | --------------------------------------------------------- |
+| `variant`  | `"ring" \| "dots" \| "bar"` | `"ring"`                                                  |
+| `size`     | `"sm" \| "md" \| "lg"`      | `"md"` — ring only                                        |
+| `muted`    | `boolean`                   | `false` — gray arc instead of accent blue                 |
+| `onAccent` | `boolean`                   | `false` — white arc for use on accent-colored backgrounds |
+
+---
+
+### Textarea
+
+Multi-line text input with custom scrollbar, character count, and clear button.
+
+```tsx
+import { Textarea } from "@dnotrever2/super-kit";
+
+<Textarea
+  label="Description"
+  placeholder="Describe the deployment..."
+  maxLength={500}
+  helpText="Markdown supported"
+  clearable
+/>
+
+// Monospace (for code / config)
+<Textarea label="config.yaml" mono />
+```
+
+| Prop                     | Type                      | Default |
+| ------------------------ | ------------------------- | ------- |
+| `label`                  | `string`                  | —       |
+| `helpText`               | `string`                  | —       |
+| `maxLength`              | `number`                  | —       |
+| `clearable`              | `boolean`                 | `false` |
+| `mono`                   | `boolean`                 | `false` |
+| `value` / `defaultValue` | `string`                  | `""`    |
+| `onValueChange`          | `(value: string) => void` | —       |
+
+Forwards a `ref` to the underlying `<textarea>`.
+
+---
+
+### Toast
+
+Notification toasts via context provider and `useToast` hook.
+
+```tsx
+// 1. Wrap your app
+import { ToastProvider } from "@dnotrever2/super-kit";
+
+<ToastProvider>
+  <App />
+</ToastProvider>
+
+// 2. Trigger from anywhere
+import { useToast } from "@dnotrever2/super-kit";
+
+function DeployButton() {
+  const { toast } = useToast();
+
+  return (
+    <Button onClick={() => toast({ variant: "ok", title: "Deployed", message: "v2.4.1 is live" })}>
+      Deploy
+    </Button>
+  );
+}
+```
+
+**`toast(options)` options**
+
+| Field      | Type                                     | Default                     |
+| ---------- | ---------------------------------------- | --------------------------- |
+| `variant`  | `"ok" \| "error" \| "warning" \| "info"` | required                    |
+| `title`    | `string`                                 | required                    |
+| `message`  | `string`                                 | —                           |
+| `duration` | `number` (ms)                            | `4000` — set `0` to persist |
+
+`toast()` returns the toast `id`. Dismiss manually with `dismiss(id)`.
+
+---
+
+### Tooltip
+
+Hover/focus tooltip above or below a child element.
+
+```tsx
+import { Tooltip } from "@dnotrever2/super-kit";
+
+<Tooltip content="Deploy to production" side="top">
+  <Button variant="primary">Deploy</Button>
+</Tooltip>
+```
+
+| Prop           | Type                              | Default  |
+| -------------- | --------------------------------- | -------- |
+| `content`      | `ReactNode`                       | required |
+| `side`         | `"top" \| "bottom"`               | `"top"`  |
+| `disabled`     | `boolean`                         | `false`  |
+| `wrapperProps` | `HTMLAttributes<HTMLSpanElement>` | —        |
+
+---
+
+## Design tokens
+
+All tokens are CSS custom properties defined in `src/styles/index.css` and available globally via `var(--token)`.
+
+### Surfaces
+
+| Token    | Value                            |
+| -------- | -------------------------------- |
+| `--bg-0` | `#0a0b0e` — deepest background   |
+| `--bg-1` | `#15181f` — card / input surface |
+| `--bg-2` | `#1f242c` — hover state          |
+| `--bg-3` | `#2a2f38` — popover / selected   |
+
+### Foreground
+
+| Token            | Value                         |
+| ---------------- | ----------------------------- |
+| `--fg-1`         | `#f1f3f5` — primary text      |
+| `--fg-2`         | `#aab2bd` — secondary text    |
+| `--fg-3`         | `#6b7280` — muted / labels    |
+| `--fg-4`         | `#4a505a` — placeholder       |
+| `--fg-on-accent` | `#ffffff` — text on accent bg |
+
+### Accent & semantic
+
+| Token                          |                        |
+| ------------------------------ | ---------------------- |
+| `--accent`                     | Blue `#3d7eff`         |
+| `--accent-hover`               | `#5b95ff`              |
+| `--accent-soft`                | `rgba(61,126,255,.14)` |
+| `--accent-ring`                | `rgba(61,126,255,.35)` |
+| `--success` / `--success-soft` | Green `#3ecf8e`        |
+| `--warning` / `--warning-soft` | Yellow `#facc15`       |
+| `--danger` / `--danger-soft`   | Red `#f0556a`          |
+
+### Typography
+
+| Token         | Value                      |
+| ------------- | -------------------------- |
+| `--font-sans` | Geist, system-ui           |
+| `--font-mono` | Geist Mono, JetBrains Mono |
+
+### Spacing (4px base)
+
+`--s-1` (4px) · `--s-2` (8px) · `--s-3` (12px) · `--s-4` (16px) · `--s-5` (20px) · `--s-6` (24px) · `--s-8` (32px) · `--s-10` (40px)
+
+### Radii
+
+`--r-1` (4px) · `--r-2` (6px) · `--r-3` (8px) · `--r-full` (999px)
+
+### Input heights
+
+`--h-input-sm` (28px) · `--h-input` (32px) · `--h-input-lg` (36px)
+
+---
+
+## Development
+
+### Start Storybook
+
+```bash
+npm run dev          # http://localhost:6006
+```
+
+Or with Docker:
+
+```bash
+make build           # docker compose up --build
+make restart
+```
+
+### Type check
+
+Always use `tsconfig.build.json` — the root config produces a false positive about `vite.config.d.ts`:
+
+```bash
+npm run typecheck
+```
+
+### Build the library
+
+```bash
+npm run build
+ls dist/super-kit.js dist/super-kit.cjs dist/index.d.ts
+```
+
+### Publish
+
+```bash
+make publish TYPE=patch    # bumps version, builds, publishes to npm
+```
+
+#### Configuração inicial (uma vez por máquina)
+
+O `make publish` exige autenticação no npm. Siga os passos abaixo:
+
+**1. Criar um token de autenticação**
+
+Acesse **npmjs.com → seu perfil → Access Tokens → Generate New Token**.
+
+Escolha **Granular Access Token** e configure:
+- **Bypass two-factor authentication (2FA)** → marque o checkbox
+- **Packages and scopes → Permissions** → selecione **"All packages"** com **"Read and write"**
+- Defina uma data de expiração e gere o token
+
+> Atenção: o token só é exibido uma vez. Copie antes de sair da página.
+
+**2. Configurar o token localmente**
+
+Crie o arquivo `.npmrc` na raiz do projeto:
+
+```
+//registry.npmjs.org/:_authToken=npm_SEU_TOKEN_AQUI
+```
+
+O `.npmrc` já está no `.gitignore` — nunca será commitado.
+
+**3. Publicar**
+
+```bash
+make publish TYPE=patch   # ou minor / major
+```
+
+### Add a new component
+
+1. Create `src/ComponentName/ComponentName.tsx`, `ComponentName.module.css`, `ComponentName.stories.tsx`, `index.ts`
+2. Export from `src/index.ts`: `export * from "./ComponentName"`
+3. Run `npm run typecheck` and confirm the story renders in Storybook

package/dist/Badge/Badge.d.ts

@@ -0,0 +1,15 @@
+import { HTMLAttributes, ReactNode } from 'react';
+export type BadgeVariant = "neutral" | "accent" | "outline" | "success" | "warning" | "danger" | "info" | "count" | "mono" | "version" | "dot";
+export type BadgeProps = HTMLAttributes<HTMLSpanElement> & {
+    variant?: BadgeVariant;
+    icon?: ReactNode;
+    pill?: boolean;
+    dismissable?: boolean;
+    onDismiss?: () => void;
+    dotColor?: string;
+    children?: ReactNode;
+};
+export declare function Badge({ variant, icon, pill, dismissable, onDismiss, dotColor, children, className, ...props }: BadgeProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Badge {
+    var displayName: string;
+}

package/dist/Badge/index.d.ts

@@ -0,0 +1 @@
+export * from './Badge';