# najm-kit
Reusable React component library for Najm applications. Provides themed UI primitives, hooks, and form components.
## Install
```bash
bun add najm-kit tailwindcss @tailwindcss/postcss
```
Peer dependencies: `react >=18`, `react-dom >=18`. Requires **Tailwind CSS v4** in the host app.
Optional peer dependencies include `recharts`, `@tanstack/react-table`,
`react-hook-form`, `@tanstack/react-query`, `leaflet`, and
`@googlemaps/js-api-loader`. Map dependencies are reached only through their
dedicated location adapter subpaths.
## Styling — the entire setup
najm-kit is a Tailwind v4, shadcn-compatible library. PostCSS config (`postcss.config.mjs`):
```js
export default { plugins: { "@tailwindcss/postcss": {} } };
```
Your global stylesheet — **two imports, that's it**:
```css
@import "tailwindcss";
@import "najm-kit/theme.css";
```
This gives you every najm-kit component styled, dark mode wired (the `.dark` class),
and a full token-backed palette you can use in your own markup too
(`bg-background`, `bg-card`, `bg-primary`, `text-muted-foreground`, `border-border`, …).
### Theming
najm-kit uses the **standard shadcn token names** (no prefix), so you rebrand by
overriding CSS variables — or paste a theme straight from
[tweakcn](https://tweakcn.com) / the shadcn registry:
```css
:root { --primary: oklch(0.55 0.2 290); --radius: 0.75rem; }
.dark { --primary: oklch(0.70 0.18 290); }
```
Add your own extra colors alongside najm-kit's:
```css
@theme { --color-success: oklch(0.7 0.18 150); } /* → bg-success, text-success */
```
Dark mode: toggle the `dark` class on `` (or any wrapper):
```ts
document.documentElement.classList.toggle("dark");
```
## Theme Provider (optional)
For scoped theming without writing CSS — useful for embedded surfaces. The provider
is opt-in: with no props it injects nothing and your `:root`/`.dark` CSS owns theming.
```tsx
import { NajmThemeProvider } from 'najm-kit';
// preset:
{children}
// or mode + accent:
{children}
// shadcn-style global radius scale:
{children}
// exact same radius for cards, tables, buttons, inputs, dialogs, etc.:
{children}
```
`rounded-full` and `rounded-none` remain explicit, so avatars, pills, switches,
and square variants keep their intended shape.
### JSON theme settings
Store one theme object in a JSON file, local storage, or your settings API:
```json
{
"mode": "dark",
"accent": "violet",
"radius": "0.75rem",
"appearance": { "borderWidth": "1px" },
"tokens": {
"primary": "oklch(0.62 0.2 290)",
"primary-foreground": "oklch(1 0 0)",
"sidebar": "oklch(0.18 0.02 290)",
"chart-1": "oklch(0.70 0.20 40)"
}
}
```
Load and apply it from the same settings state used by your theme editor:
```tsx
import rawTheme from './theme.json';
import { NajmThemeProvider, parseNajmThemeConfig } from 'najm-kit';
const initialTheme = parseNajmThemeConfig(rawTheme);
function App() {
const [theme, setTheme] = useState(initialTheme);
return (
{children}
);
}
```
Changing the state updates the complete theme immediately. Use
`stringifyNajmThemeConfig(theme)` when persisting it, and parse settings loaded
from an API or local storage with `parseNajmThemeConfig` before applying them.
## Components
Import from `najm-kit`:
```tsx
import { NButton, buttonVariants } from 'najm-kit';
import { Input } from 'najm-kit';
import { Card, CardHeader, CardTitle, CardContent } from 'najm-kit';
import { Dialog, DialogContent, DialogTrigger } from 'najm-kit';
import { DataTable } from 'najm-kit';
import { Form, FormInput, useNForm } from 'najm-kit';
```
### Available Primitives
| Category | Components |
|----------|-----------|
| Actions | NButton, IconButton, toggleVariants |
| Forms | Input, Textarea, Label, Select, Checkbox, RadioGroup, Switch, DateInput, FileInput, ImageInput, AvatarInput |
| Feedback | Alert, Badge, Progress, Spinner, Toast, NLoadingState, NErrorState, NEmptyState, NForbiddenState, NNotFoundState |
| Layout | Card, Sheet, Dialog, Popover, DropdownMenu, Tabs |
| Data | Table (NTable), StatCard, DetailList, CredentialsCard |
| Overlays | Command palette, Tooltip, Toast |
## Images and avatars
Three components, one fallback rule. Each tries its sources in order, tries a
source at most once, and discards what it knows about a failure the moment the
sources change.
### `NImage` — plain ``
For a logo or an icon whose box the caller's CSS already owns. No layout is
invented, and `onError` is forwarded rather than swallowed.
```tsx
import { NImage } from 'najm-kit';
```
### `NAvatar` — person or record
The image is a native `` loaded directly by the browser, so a same-origin
protected route works with the session the page already has, and the package
needs no knowledge of which routes are protected.
```tsx
import { NAvatar } from 'najm-kit';
```
- The primary source is tried first, then `fallbackSrc`, then the initials.
- `version` (or `srcVersion`) is appended as `?v=…` to every remote source, so a
re-upload is not served from cache. `data:` and `blob:` sources are left alone.
- Initials stay visible until an image paints and come back if every source
fails — a transparent PNG never shows letters through itself.
- `imageProps` reaches the element for `loading`, `sizes`, `crossOrigin`,
`referrerPolicy`, and the load/error handlers. It defaults to `loading="lazy"`,
and supplied handlers are composed with the fallback chain rather than
replacing it.
### `NNextImage` — optimized, from `najm-kit/next`
Same fallback contract with Next's optimizer, layout reservation, `fill`, and
`sizes`. It lives only in the `najm-kit/next` entry, because the root package
stays installable without Next.
```tsx
import { NNextImage } from 'najm-kit/next';
// A public asset: let the optimizer resize and re-encode it.
```
For an asset the browser must fetch directly — one behind an authenticated route,
typically — the *application* says so:
```tsx
```
`unoptimized` is passed at the call site rather than inferred from the URL:
which routes are protected is the application's fact, not something a package
can read off a path. It changes delivery mechanics only — session validation,
permissions, privacy projection, and what bytes come back all remain the
backend's.
## App snapshot
`NajmKitProvider` from `najm-kit/app` owns Kit's UI/i18n/formatting/preferences
stack and accepts the standard public server snapshot directly. The
snapshot seeds language, theme, time zone, design, and branding; application
policy stays explicit:
```tsx
{children}
```
Existing `initialLanguage`, `initialTheme`, `initialTimeZone`, `initialDesign`,
and `initialBranding` props remain available as explicit overrides. The
snapshot is structural, so Kit does not depend on the server or Next package.
The former `NajmAppProvider` name and matching types remain deprecated aliases
to this same implementation and context identity. Full Auth/Query/Theme stacks
should use `NajmAppProvider` from `najm-next/app/client` instead.
## Status badges
`` ships the whole thing: the lifecycle, review,
fulfilment, payment and attendance vocabulary mapped onto the semantic colors,
labels for it in English, French, Arabic and Spanish, and the soft pill shape a
status wears. No configuration, no provider, no catalog:
```tsx
import { NBadge } from 'najm-kit';
// warning, soft pill, "Out for delivery"
// destructive
// neutral, "Nebulous"
```
Soft and pill are the defaults for a *status* badge only. A content badge —
`Beta` — keeps the solid look it has always had.
### The application's own wording
An application whose catalog is keyed by the convention needs no map at all.
`status.` is looked up through the provider's `t`, and a hit wins over
the packaged label:
```json
{ "status": { "in_preparation": "Purchasing and preparation" } }
```
`NajmKitProvider` and `NajmAppProvider` supply both the translator and the
active language, so switching language relabels every badge below without a
remount. Mounting `NajmUIProvider` directly, pass `t` and `language` yourself.
Anything the convention does not cover goes on `badgeDefaults`, which lives on
`NajmUIProvider` and is inherited by `NajmNextUIProvider` and
`NajmAppProvider`:
```tsx
```
### The same labels as plain text
`formatStatusLabel` resolves the identical text without a badge, from the
server-safe `najm-kit/format` leaf — for a sentence, an export, or an email:
```ts
import { formatStatusLabel } from 'najm-kit/format';
formatStatusLabel('out_for_delivery', { language: 'fr' }); // "En cours de livraison"
formatStatusLabel('in_preparation', { language: 'fr', t }); // the catalog's wording
```
### Resolution, most specific first
1. An explicit prop beats every provider default, which beats the packaged one.
2. `label` beats string children; string children beat any resolved label.
3. A `statusLabels` literal beats a `statusLabelKeys` catalog lookup, which
beats the conventional `status.` lookup, which beats the packaged
label for the active language.
4. A key the catalog does not hold never renders as itself — it falls through.
5. An unmapped status is humanized (`bespoke_state` → `Bespoke State`).
6. A per-instance `statusMap`/`iconMap` merges over the provider's, which
merges over the packaged one, so overriding one status costs one status.
7. Provider and packaged status defaults apply **only** when `status` is set.
A regional tag resolves to its base language (`fr-MA` → `fr`), and an
unpackaged language falls back to English rather than to the raw token.
Statuses are matched through one rule, exported as `normalizeStatusToken`, so
`Out-For-Delivery `, `out for delivery`, and `out_for_delivery` are the same
key for colors, icons, and labels alike. Badge text is presentation: it renames
nothing in the backend and validates no lifecycle transition.
## Feedback states
Five public state components cover the reusable cases every application
otherwise repeats: `NLoadingState`, `NErrorState`, `NEmptyState`,
`NForbiddenState`, and `NNotFoundState`. They share one layout frame and one
provider-defaults channel, so an application configures its copy once and
every consumer below inherits it.
### Surfaces
Three layouts, one prop. `surface` selects the frame:
| `surface` | Use it for | What it does |
| --- | --- | --- |
| `"inline"` (default) | A small slot inside an existing component | Legacy sizing, no landmark |
| `"panel"` | A table body, card body, dialog, or sheet | Centered with a minimum height, no page gutter, no landmark |
| `"page"` | A real route-level state | Uses page spacing from the design config; renders through a non-`` root |
`NLoadingState.fullScreen` keeps its fixed viewport overlay regardless of
surface — it always wins.
```tsx
import { NLoadingState, NErrorState, NEmptyState } from 'najm-kit';
// Inline (default): drop into a card or section.
// Panel: table body or dialog content.
// Page: route-level empty state. Never introduces a second .
refetch()}
/>
```
### Provider defaults
Pass one `feedbackDefaults` map to `NajmUIProvider` (or to `NajmAppProvider`
through it) and every feedback state beneath uses it. There is one place for
loading, empty, error, retry, forbidden, and not-found labels, and a single
language change recomputes them all without remounting the tree.
```tsx
import { NajmAppProvider } from 'najm-kit/app';
```
Resolution order, most specific first:
1. An explicit component prop.
2. A literal in `feedbackDefaults.labels`.
3. A translated `feedbackDefaults.labelKeys` value resolved through the
provider's existing structural `t` function.
4. `` `.` `` resolved through the same `t`, where `prefix`
defaults to `common.feedback`.
5. The current packaged English fallback, when that field has one.
#### The prefix convention
Step 4 is the reason most applications need no `feedbackDefaults` at all. Name
the nine catalog entries after the fields — `common.feedback.emptyTitle`,
`common.feedback.retryLabel`, and so on — and a provider that already has a
translator resolves every feedback state with no mapping object to write or
memoize:
```tsx
```
Use `prefix` to point at a different branch, and `FeedbackKey` to type
a translator against exactly those nine keys:
```tsx
import type { FeedbackKey } from 'najm-kit';
```
Unlike `buildToolbarLabels` and `buildPaginationLabels`, a translator result
equal to the key it was handed is treated as *missing* here rather than
rendered. The prefix is a convention an application may never have adopted, so
an unanswered key falls through to packaged English instead of painting
`common.feedback.emptyTitle` across an empty state. The same rule applies to an
explicit `labelKeys` entry, which makes a typo in the mapping degrade to English
rather than to visible key text.
Generic `NErrorState.message` and `NEmptyState.description` deliberately have
no packaged fallback — the no-provider render must look the same as it did
before this contract shipped. A configured `errorMessage` opts the generic
error state into rendering a body; absent that opt-in, the existing
no-body render is preserved.
### Forbidden and not-found
Two first-class preset states for the routes every application grows:
```tsx
import { NForbiddenState, NNotFoundState } from 'najm-kit';
// Forbidden: provider copy + ShieldOff icon + page surface by default.
Back to dashboard}
/>
// Not found: provider copy + Compass icon + page surface by default.
Back to dashboard}
/>
```
Both are presentation only. They do not know the dashboard URL, render a
Next `Link`, redirect, or write route metadata — those belong to the
application's `not-found.tsx` / `forbidden/page.tsx` files.
### Root and `najm-kit/app` imports
Both entries export the same five state components. Pick the one that matches
your boundary:
```tsx
// Client feature code: import from the root barrel.
import { NEmptyState } from 'najm-kit';
// Next Server Component route: import from najm-kit/app, which is the
// Client Component boundary. A route file can render a state component
// without authoring a local "use client" wrapper.
import { NNotFoundState } from 'najm-kit/app';
```
## Global form development tools
Enable schema-driven test values once on the full application provider. Every
`NForm` and `WizardForm` below it then fills from its Zod schema when F8 is
pressed; applications do not need a second provider or a form-fill helper.
```tsx
import { NajmAppProvider } from "najm-kit/app";
;
```
Pass a boolean to control it from application settings:
```tsx
```
Forms with live relation options can override only those fields. The provider
still owns enablement and Najm Kit still owns schema traversal and generation.
```tsx
{/* fields */}
```
## ImageInput and AvatarInput
`ImageInput` and `AvatarInput` ship with a resilient preview contract so
consumers do not need to wrap them with application-specific preview
components.
Source precedence:
- When `value` is a non-empty string URL, candidates are tried in order:
1. `value` is the primary preview source.
2. If the primary source fails, `fallbackImage` is tried when supplied.
3. `defaultImage` is the last-resort fallback.
- When `value` is `null` or empty, only `defaultImage` is tracked. The
`fallbackImage` is intentionally not used in the empty state — a null
`value` is the consumer's empty-state signal, and only the configured
default participates in the failed-default → unavailable transition.
If `defaultImage` itself fails, `onPreviewError({ source: "default" })`
fires and the unavailable state is rendered.
Candidate URLs are deduplicated so the same failing URL is never retried
through multiple stages. When every candidate fails, the broken `` is
unmounted and `unavailableContent` (or a neutral default) is rendered in its
place. A `data-image-input-state="empty" | "preview" | "fallback" | "unavailable"`
marker is exposed for styling, testing, and consumer diagnostics.
Candidate URLs are deduplicated so the same failing URL is never retried
through multiple stages. When every candidate fails, the broken `` is
unmounted and `unavailableContent` (or a neutral default) is rendered in its
place. A `data-image-input-state="empty" | "preview" | "fallback" | "unavailable"`
marker is exposed for styling, testing, and consumer diagnostics.
```tsx
import { ImageInput } from "najm-kit";
Logo unavailable}
imageClassName="object-contain"
imageVersion={cacheBustVersion}
replaceAriaLabel="Replace workspace logo"
clearAriaLabel="Remove workspace logo"
onPreviewError={(err) => log(err)}
/>
```
Key behaviors:
- The replace and clear controls are real `