@salilvnair/dui 1.0.0 → 1.0.2

package/README.md

@@ -1,8 +1,48 @@
 # @salilvnair/dui
 
-Daakia UI — a React component library shared across ck8t and daakia. Ships as
-a compiled ESM bundle with generated `.d.ts` types; peer dependencies are
-`react`, `react-dom`, and `zustand`.
+**Daakia UI** — a React 19 + TypeScript component library shared across
+[daakia](https://github.com/salilvnair) and ck8t. 65+ components, a
+CSS-variable theme system, and a Monaco-backed code editor that's entirely
+optional — install it only if you use it.
+
+[![npm version](https://img.shields.io/npm/v/@salilvnair/dui.svg)](https://www.npmjs.com/package/@salilvnair/dui)
+[![license](https://img.shields.io/npm/l/@salilvnair/dui.svg)](https://github.com/salilvnair/dui/blob/main/LICENSE)
+
+Repository: **https://github.com/salilvnair/dui**
+
+---
+
+## Table of contents
+
+- [Features](#features)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Component catalog](#component-catalog)
+- [Theming](#theming)
+- [The code editor — Monaco is optional](#the-code-editor--monaco-is-optional)
+- [Extending MarkdownView's language support](#extending-markdownviews-language-support)
+- [TypeScript](#typescript)
+- [Local development](#local-development)
+- [Publishing to npm](#publishing-to-npm)
+- [License](#license)
+
+---
+
+## Features
+
+- **65+ components** — inputs, buttons, navigation, display, overlays,
+  layout, and a full debug/editor toolkit (see [catalog](#component-catalog))
+- **CSS-variable theming** — every color is a `--color-*` custom property;
+  retheme by overriding variables on `:root` or any container, no rebuild
+- **Size system** — one `size` prop (`xxs`–`xxxl`) threaded through every
+  component via `<DuiProvider>`, or override per-instance
+- **Optional Monaco editor** — `EditorView`/`DiffEditorView`/`DebugEditorView`
+  render a plain-text fallback out of the box; Monaco is a genuinely optional
+  peer dependency, not a hard requirement (see below — this is the part of
+  the library most worth understanding before you adopt it)
+- **Tree-shakeable ESM** — compiled output, real `.d.ts` types, multi-entry
+  build so `import '@salilvnair/dui/monaco-setup'` is the *only* way Monaco
+  code ever enters your bundle
 
 ## Install
 
@@ -10,32 +50,148 @@ a compiled ESM bundle with generated `.d.ts` types; peer dependencies are
 npm install @salilvnair/dui react react-dom zustand
 ```
 
-Import the stylesheet once in your app's entry point:
+Import the stylesheet once, in your app's entry point:
 
 ```ts
 import '@salilvnair/dui/style.css';
 ```
 
-## Usage
+## Quick start
 
 ```tsx
-import { ButtonView, TabView, DuiProvider } from '@salilvnair/dui';
+import { DuiProvider, ButtonView, TextInputView, TabView } from '@salilvnair/dui';
+import '@salilvnair/dui/style.css';
 
-function App() {
+export function App() {
   return (
     <DuiProvider size="md">
-      <ButtonView>Click me</ButtonView>
+      <TextInputView placeholder="Search…" value={value} onChange={setValue} />
+      <ButtonView onClick={handleSubmit}>Submit</ButtonView>
     </DuiProvider>
   );
 }
 ```
 
-## Monaco is optional
+`DuiProvider` is optional — every component works standalone with sensible
+defaults. Wrap your app in it when you want a single place to set the
+default `size` or accent color for the whole tree.
+
+## Component catalog
+
+<details>
+<summary><b>Inputs</b> (14)</summary>
+
+`TextInputView` · `MultilineInputView` · `SelectInputView` ·
+`SelectTextInputView` · `SegmentedControlView` · `TagInputView` ·
+`CheckboxView` · `ToggleSwitchView` · `SliderView` · `DurationInputView` ·
+`HighlightedInputView` · `SearchInputView` · `KeyValueTableView` ·
+`MergedInputView`
+
+</details>
+
+<details>
+<summary><b>Editor / Debug toolkit</b></summary>
+
+`EditorView` · `DebugEditorView` · `DiffEditorView` · `DebugView` — see
+[Monaco is optional](#the-code-editor--monaco-is-optional) before adopting these.
+
+</details>
+
+<details>
+<summary><b>Buttons</b> (4)</summary>
+
+`ButtonView` · `IconButtonView` · `DropDownButtonView` · `SplitButtonView` ·
+`SegmentedView` · `AIButtonView`
+
+</details>
+
+<details>
+<summary><b>Navigation</b> (5)</summary>
+
+`TabView` · `TabBarView` · `PilledTabView` · `ContextMenuView` ·
+`SideNavView` · `SettingsNavView`
+
+</details>
+
+<details>
+<summary><b>Display</b> (19)</summary>
+
+`ChipView` · `StatusIndicatorView` · `LoaderView` · `EmptyStateView` ·
+`ColoredTextView` · `StatsCardView` · `DottedCardView` · `DataTableView` ·
+`CodeBlockView` · `MarkdownView` · `PromptCardView` · `PromptLibraryListView` ·
+`PromptLibraryEditorView` · `StageView` · `HudView` · `JsonTreeView` ·
+`ExpandableLogEntryView` · `CopyButtonView` · `YamlKeyChip` ·
+`FeatureCategoryView`
+
+</details>
+
+<details>
+<summary><b>Overlays</b> (3)</summary>
+
+`ModalView` · `InfoPopupView` · `ToastView`
+
+</details>
+
+<details>
+<summary><b>Layout</b> (8)</summary>
+
+`ResizablePanelView` · `SplitPanelView` · `BottomPanelView` · `FolderView` ·
+`CollapsibleSectionView` · `SpacerView` · `SettingsNavView` · `SideNavView`
+
+</details>
+
+<details>
+<summary><b>More</b></summary>
 
-`EditorView`, `DiffEditorView`, and `DebugEditorView` render a lightweight
-plain-text fallback by default — **`@monaco-editor/react` and `monaco-editor`
-are not required dependencies.** If you don't use these three components,
-you never need to install them.
+`DuiProvider` (size/theme context) · `LiveColorCustomizer` ·
+`ThemeCardSelectorView` · `FormDataTableView` · `RearrangeView` ·
+`HiddenKeyValueItemView` · full icon set (`@salilvnair/dui` re-exports every
+icon used internally)
+
+</details>
+
+Every component ships full TypeScript prop types — explore them via your
+editor's autocomplete, or browse `src/lib` in the
+[repo](https://github.com/salilvnair/dui).
+
+## Theming
+
+All design tokens are CSS custom properties, defined via Tailwind v4's
+CSS-first `@theme` syntax and shipped in `dist/style.css`:
+
+```css
+:root {
+  --color-primary: #6366f1;
+  --color-surface: #1e1e1e;
+  --color-surface-border: #414141;
+  /* … */
+}
+```
+
+Override any subset on `:root` (global) or on a wrapping element (scoped —
+e.g. to theme one panel differently). Programmatic helpers live under the
+`theme/*` subpath exports:
+
+```ts
+import { SCHEMA } from '@salilvnair/dui/theme/core';       // token schema (group/key/cssVar/comment)
+import { generateYaml } from '@salilvnair/dui/theme/utils'; // export current theme as YAML
+import { ThemeVarEditor } from '@salilvnair/dui/theme/editor'; // UI for adding a new theme variable
+```
+
+## The code editor — Monaco is optional
+
+`EditorView`, `DiffEditorView`, and `DebugEditorView` do **not** require
+`@monaco-editor/react` or `monaco-editor` to be installed. Without them,
+these components render a lightweight plain-text fallback (a styled
+`<textarea>` and a small line-diff view) — fully functional for basic
+editing, just without IntelliSense, breakpoints, or Monaco's diff engine.
+
+```tsx
+import { EditorView } from '@salilvnair/dui';
+
+// Works immediately, zero extra installs — renders the plain-text fallback.
+<EditorView value={code} onChange={setCode} language="json" />
+```
 
 To get the real Monaco-backed editor:
 
@@ -44,43 +200,66 @@ npm install @monaco-editor/react monaco-editor
 ```
 
 ```ts
-// once, at app bootstrap
+// once, at app bootstrap — before any EditorView renders
 import '@salilvnair/dui/monaco-setup';
 ```
 
-This self-hosts Monaco (inline workers, no CDN — works under strict CSP,
-e.g. VS Code webviews) and registers the real editor implementation.
-Skipping this import is fine; `EditorView` keeps working as a plain textarea.
+That import self-hosts Monaco: inline workers (no CDN — works under a strict
+CSP, e.g. inside a VS Code extension webview), a VS Code–accurate dark/light
+theme, and registration of the real editor implementation. `EditorView`
+automatically starts rendering the Monaco-backed version the moment this
+import has run; skip it and everything still works, just without Monaco.
 
-### Why not just install Monaco automatically?
+**Why not auto-install Monaco, or fall back to a CDN?** `@monaco-editor/react`
+defaults to lazy-loading Monaco assets from a public CDN when you don't
+self-host — a reasonable default for a plain public web page, but wrong for
+CSP-restricted environments (webviews, offline apps, intranets) where that
+CDN is unreachable. Rather than silently guess, this library requires an
+explicit opt-in (`monaco-setup`) and never attempts the CDN path at all.
 
-`@monaco-editor/react` doesn't depend on `monaco-editor` itself — it lazy-loads
-Monaco from a public CDN by default. If your environment blocks that CDN (most
-VS Code extension webviews, offline apps, strict-CSP deployments do), the only
-correct answer is genuine self-hosting via `monaco-setup`, which is why that
-import is explicit rather than automatic.
+**Bundle boundary, verified, not assumed:** `dist/index.js` (the main entry —
+everything except `EditorView` internals) contains zero references to
+`@monaco-editor/react` or `monaco-editor`. Only `dist/monaco-setup.js`
+does. This is checked as part of the release process, not just documented —
+see [Publishing](#publishing-to-npm).
 
-### Extending MarkdownView's language support
+## Extending MarkdownView's language support
 
-`MarkdownView`'s syntax highlighting registers a curated set of languages
+`MarkdownView` ships syntax highlighting for a curated set of ~16 languages
 (js/ts/json/xml/html/css/bash/yaml/python/sql/ruby/rust/csharp/kotlin/graphql/markdown)
-via `highlight.js/lib/core` rather than the full ~190-language `highlight.js`
-package, to keep the bundle small. Adding a language currently requires a
-change in this repo and a version bump — there's no way to register
-additional languages from a consuming app yet.
-
-## Theming
+via `highlight.js/lib/core`, rather than highlight.js's full ~190-language
+bundle, to keep the library small. Add more without waiting on a release:
 
 ```ts
-import { SCHEMA } from '@salilvnair/dui/theme/core';
-import { generateYaml } from '@salilvnair/dui/theme/utils';
-import { ThemeVarEditor } from '@salilvnair/dui/theme/editor';
+import { registerMarkdownLanguage } from '@salilvnair/dui';
+import lua from 'highlight.js/lib/languages/lua';
+
+registerMarkdownLanguage('lua', lua); // once, at app startup
 ```
 
-All colors are CSS custom properties (`--color-*`) — override them on
-`:root` or scope them to a container to retheme without recompiling.
+## TypeScript
 
----
+Full type declarations ship in `dist/`, generated from source — no
+`@types/@salilvnair__dui` needed. `peerDependencies` cover `react`,
+`react-dom`, and `zustand`; `@monaco-editor/react` and `monaco-editor` are
+`peerDependenciesMeta.optional` peers (see above).
+
+## Local development
+
+```bash
+git clone https://github.com/salilvnair/dui.git
+cd dui
+npm install
+npm run dev            # showcase app at localhost:5173
+```
+
+Open `http://localhost:5173/#dui` for the component showcase — every
+component has a live playground, examples, and prop docs.
+
+```bash
+npm run build           # builds the showcase app (for deploying docs/demo)
+npm run build:lib       # builds the publishable library into dist/
+```
 
 ## Publishing to npm
 
@@ -173,7 +352,7 @@ git push && git push --tags
 
 ### Troubleshooting
 
-**Consumer's build fails resolving `@monaco-editor/react`even though they never use `EditorView`**
+**Consumer's build fails resolving `@monaco-editor/react` even though they never use `EditorView`**
 → Something reintroduced a static import of it into `index.js`. Re-run the
 Monaco boundary grep in Step 2 — this is the one regression this package
 must never ship.
@@ -183,3 +362,7 @@ must never ship.
 `@salilvnair/dui/monaco-setup`. `EditorView` never falls back to the CDN
 loader on its own — it only ever renders the plain-text fallback or the
 self-hosted Monaco registered by `monaco-setup`.
+
+## License
+
+MIT © [Salil V Nair](https://github.com/salilvnair) — see [LICENSE](./LICENSE).