eidotter 0.20.0 → 0.20.1

package/README.md

@@ -1,23 +1,42 @@
-# eiDotter - DOS Terminal Design System
+# eiDotter
 
-A DOS-themed React component library with authentic CGA terminal aesthetics.
+```
+┌──────────────────────────────────────────────┐
+│  C:\> EIDOTTER_                              │
+│                                              │
+│  DOS terminal design system for React.       │
+│  Authentic CGA phosphor. WCAG AA.            │
+│  Tree-shakable. No CSS-in-JS runtime.        │
+└──────────────────────────────────────────────┘
+```
+
+[![npm](https://img.shields.io/npm/v/eidotter.svg?color=ffb000&labelColor=020003&label=npm)](https://www.npmjs.com/package/eidotter)
+[![CI](https://img.shields.io/github/actions/workflow/status/CinimoDY/eiDotter/build.yml?branch=main&color=ffb000&labelColor=020003&label=CI)](https://github.com/CinimoDY/eiDotter/actions/workflows/build.yml)
+[![license](https://img.shields.io/badge/license-CC--BY--NC--4.0-ffb000?labelColor=020003)](./LICENSE.md)
+[![React](https://img.shields.io/badge/React-18%20%7C%2019-ffb000?labelColor=020003)](https://react.dev/)
+
+**eiDotter** is a React component library that takes the DOS/CGA terminal aesthetic seriously: authentic 16-color palette, bitmap-accurate typography, phosphor glow physics, keyboard-first interactions. 36 components across forms, navigation, windowing, timelines, and terminal chrome — shipped as ES modules with a prebuilt stylesheet so consumers don't need Tailwind to use it.
+
+→ **[Storybook](https://cinimody.github.io/eiDotter/)**  ·  **[CHANGELOG](./CHANGELOG.md)**  ·  **[Issues](https://github.com/CinimoDY/eiDotter/issues)**  ·  **[npm](https://www.npmjs.com/package/eidotter)**
+
+---
 
-## Installation
+## Install
 
 ```bash
 npm install eidotter
 ```
 
-## Quick Start
+## Quick start
 
 ```tsx
-import { Terminal, Button, Alert } from 'eidotter';
-import 'eidotter/styles';      // All styles: fonts, tokens, components
+import { Terminal, Alert, Button } from 'eidotter';
+import 'eidotter/styles';
 
 function App() {
   return (
     <Terminal title="MY-APP.EXE">
-      <Alert type="info" title="Welcome">
+      <Alert color="success" title="System Ready">
         DOS interface loaded successfully.
       </Alert>
       <Button variant="primary">Execute</Button>
@@ -26,255 +45,174 @@ function App() {
 }
 ```
 
-## Setup
-
-### Basic (no Tailwind needed)
-
-Import the styles. All component styling, fonts, and design tokens are pre-compiled — no build tools required.
-
-```tsx
-import 'eidotter/styles';      // Fonts, tokens, components, Tailwind utilities
-
-// Optional: import a theme
-import 'eidotter/themes/amber-mono.css';
+A single CSS import pulls everything: font, tokens, component styles, and compiled Tailwind utilities. Tailwind is **not** required to use eiDotter — consume it as plain React + one stylesheet.
 
-// Optional (v0.19.4+): DOS typography utility classes for raw HTML / MDX / prose
-// 12 classes: .dos-page, .dos-hero, .dos-h1–.dos-h5, .dos-body, .dos-body-lg,
-// .dos-caption, .dos-micro, .dos-label, .dos-code, .dos-scanlines
-import 'eidotter/utilities';
-```
+## Setup
 
-Individual imports are still available for granular control:
+### Styles
 
 ```tsx
-import 'eidotter/fonts.css';   // Flexi IBM VGA True @font-face
-import 'eidotter/tokens.css';  // CSS variable definitions
-import 'eidotter/styles';      // Component CSS + Tailwind utilities
-import 'eidotter/utilities';   // Opt-in .dos-* typography classes (v0.19.4+)
+import 'eidotter/styles';                    // Everything: font + tokens + components + utilities
+import 'eidotter/themes/amber-mono.css';     // Optional: theme override
+import 'eidotter/utilities';                 // Optional: .dos-* typography classes for raw HTML
 ```
 
-**Font:** eiDotter uses [Flexi IBM VGA True v2](https://int10h.org/blog/2018/05/flexi-ibm-vga-scalable-truetype-font/) — an aspect-corrected vector remake of the IBM VGA BIOS font (CC BY-SA 4.0). The "True" variant matches authentic 4:3 VGA proportions with an extended character set (Greek, Cyrillic, Hebrew, Latin). The `fonts.css` import loads the bundled TTF via `@font-face`.
+Granular imports are still available (`eidotter/fonts.css`, `eidotter/tokens.css`) if you want to override the font or tokens independently.
 
-Two fontFamily tokens are exported, with distinct intent:
+### With Tailwind
 
-- **`font-dos`** → `"Flexi IBM VGA True", monospace` — the default. Preserves the terminal aesthetic on degraded `@font-face` loads (strict CSP, web-fonts disabled, reader mode).
-- **`font-dos-fallback`** → `monospace` only — intentionally bare, as a **fail-loud diagnostic** utility for surfaces that want to surface font-loading failures explicitly. Compose `font-dos font-dos-fallback` when you want strict Flexi-or-nothing behavior.
-
-### With Tailwind CSS
-
-Use eidotter's design tokens as Tailwind utility classes in your own code.
-
-```bash
-npm install tailwindcss
-```
+If you already use Tailwind, register eiDotter's preset and drop the `eidotter/styles` import (the preset compiles utilities in your build):
 
 ```js
 // tailwind.config.js
 module.exports = {
   presets: [require('eidotter/tailwind.preset')],
-  content: ['./src/**/*.{js,jsx,ts,tsx}'],
+  content: ['./src/**/*.{ts,tsx,jsx}'],
 };
 ```
 
 ```tsx
-// Now use eidotter tokens as Tailwind classes
 <div className="bg-dos-bg-primary text-dos-text-accent font-dos">
   DOS terminal content
 </div>
 ```
 
-The preset auto-registers `tailwindcss-react-aria-components` and `tailwindcss-animate` via require-if-available. Consumers who already list either plugin in their own Tailwind config may see duplicate-variant warnings from Tailwind — either rely on the preset's registration alone, or pass those plugins explicitly in your config (they're idempotent, but the duplicate registration is noisy).
+The preset auto-registers `tailwindcss-react-aria-components` and `tailwindcss-animate` if they resolve. Migrating from the pre-0.19.2 dual-preset split? See [CHANGELOG → 0.19.2](./CHANGELOG.md#0192--2026-04-18).
 
-#### Migration from 0.19.1 and earlier
+## Documentation
 
-In 0.19.2 the two older presets (`eidotter/tailwind.preset` and `eidotter/tailwind.preset.enhanced`) were merged into a single `eidotter/tailwind.preset` that includes all tokens plus the React Aria + animate plugins. The enhanced subpath is now a deprecated alias that logs a one-time `console.warn` on load and will be removed in 0.21.0:
+| | |
+|---|---|
+| **Live docs** | [Storybook](https://cinimody.github.io/eiDotter/) — every component with stories, controls, and source |
+| **Design tokens** | `src/tokens/*.json` (DTCG format) → `tokens.css` via Style Dictionary |
+| **Themes** | `amber-mono` (default), `cga-amber`, `cga-mode4-p0/p1`, `cga-mode5` |
+| **Font** | [Flexi IBM VGA True v2](https://int10h.org/blog/2018/05/flexi-ibm-vga-scalable-truetype-font/) — aspect-corrected vector remake of the IBM VGA BIOS, CC BY-SA 4.0. Bitmap-authentic single-weight; all `fontWeight` tokens resolve to 400 |
+| **Icons** | [pixelarticons](https://github.com/halfmage/pixelarticons) (MIT) — DOS pixel-art glyphs |
+| **Accessibility** | WCAG AA, React Aria primitives under interactive components, `prefers-reduced-motion` + `prefers-contrast` honored throughout |
 
-```diff
-- presets: [require('eidotter/tailwind.preset.enhanced')]
-+ presets: [require('eidotter/tailwind.preset')]
-```
+## Components
 
-No behavior change — the merged preset already carries everything the enhanced preset used to add.
-
-## Available Components (36)
-
-| Component | Description |
-|-----------|-------------|
-| Accordion | Collapsible content sections (Section, AccordionFill) |
-| Alert | Inline alert banner with featured icon, actions, and 6 color variants |
-| Badge | Status indicators with variant support |
-| Breadcrumb | Navigation path display |
-| Button | DOS-style buttons (primary, secondary, ghost, link) |
-| Card | Content container with variants (elevated, bordered, glow, interactive, minimal, callout) |
-| ChatMessage | Chat message with role-based DOS styling and streaming cursor |
-| ChatHistory | Scrollable message list with auto-scroll and `role="log"` |
-| ChatInput | Multiline textarea with Enter-to-send |
-| ChatContainer | Composes ChatHistory + ChatInput — place inside Terminal for DOS chat |
-| Checkbox | DOS-style checkbox with `[X]` bracket indicator |
-| CmdPalette | ⌘K / Ctrl+K command palette overlay with scored search + keyboard navigation |
-| CommandPrompt | Interactive command-line input with blinking cursor |
-| DosFigure | Demoscene-style painted-screen media placeholder with scanline sweep + optional pins |
-| FilterBar | Multi-select toggle group for faceted filtering |
-| Footer | Site footer with legal links (Impressum + Datenschutz) |
-| Header | Sticky site header composing branding + Nav — retro/modern variants |
-| Icon | SVG icons backed by pixelarticons (MIT) — authentic DOS pixel art |
-| InlineExpand | Inline disclosure widget for expanding text within prose |
-| InlineLink | In-flow navigational anchor — dotted underline, phosphor-invert hover, external variant |
-| Input | Text input with DOS styling and error variant |
-| Modal | Dialog overlay with title bar and close button |
-| Nav | Responsive navigation with desktop/mobile variants |
-| Notification | Toast popup with layered amber glow, auto-dismiss, and progress variant |
-| Progress | DOS-style progress bar with block characters |
-| RetroEffects | CRT effects (scanlines, noise, phosphor glow) |
-| Separator | Horizontal/vertical divider |
-| Stat | Key-value display for metrics and statistics |
-| Switch | Toggle switch for on/off states |
-| Tabs | Tabbed interface navigation |
-| Tag | Interactive labels for tags, categories, and filter chips |
-| Terminal | DOS window with title bar and content area |
-| TextScramble | DOS text decode/scramble animation effect |
-| TimelineContainer | Multi-zoom timeline with year/month/day/hour views |
-| TimelineNode | Timeline/stepper axis markers with shapes and glow |
-| Tokens | Design token reference display (Storybook only) |
-
-## Component Examples
-
-### Header
+36 components across five families — [complete catalog in Storybook](https://cinimody.github.io/eiDotter/).
 
-```tsx
-<Header brandName="DMNC.TECH" items={navItems} variant="retro">
-  {/* or use children for custom branding */}
-</Header>
-```
+<details>
+<summary><strong>Windowing &amp; shell</strong> — Terminal, Modal, CommandPrompt, CmdPalette, Header, Footer, Nav</summary>
 
-### Terminal
+| Component | Purpose |
+|---|---|
+| `Terminal` | DOS window with title bar, minimize/maximize/close controls |
+| `Modal` | Dialog overlay on React Aria primitives (ModalOverlay + Modal + Dialog) |
+| `CommandPrompt` | Interactive command-line input with blinking cursor |
+| `CmdPalette` | ⌘K overlay with scored search, keyboard nav, configurable hotkey |
+| `Header` | Sticky site header (retro / modern variants), composes branding + Nav |
+| `Footer` | Site footer with default legal links (Impressum + Datenschutz) |
+| `Nav` | Responsive navigation with desktop + mobile variants |
 
-```tsx
-<Terminal
-  title="PROGRAM.EXE"
-  size="medium"
-  closeable
-  onClose={() => console.log('closed')}
->
-  <p>Terminal content here</p>
-</Terminal>
-```
+</details>
 
-### Button
+<details>
+<summary><strong>Content surfaces</strong> — Card, Accordion, Alert, Badge, Tag, Notification, Stat, Progress, Separator, Breadcrumb</summary>
 
-```tsx
-<Button variant="primary" size="md">
-  Click Me
-</Button>
+| Component | Purpose |
+|---|---|
+| `Card` | Content container (elevated, bordered, glow, interactive, minimal, callout) |
+| `Accordion` | Collapsible content sections (Section + AccordionFill) |
+| `Alert` | Inline alert banner with featured icon, actions, 6 color variants |
+| `Badge` | Status indicator chips |
+| `Tag` | Interactive labels for tags, categories, filter chips |
+| `Notification` | Toast popup with layered amber glow, auto-dismiss, progress variant |
+| `Stat` | Key-value display for metrics |
+| `Progress` | DOS-style progress bar with block characters |
+| `Separator` | Horizontal / vertical divider |
+| `Breadcrumb` | Navigation path display |
 
-<Button variant="ghost" loading>
-  Processing...
-</Button>
-```
+</details>
 
-### Alert
+<details>
+<summary><strong>Input</strong> — Button, Input, Checkbox, Switch, Tabs, FilterBar</summary>
 
-```tsx
-<Alert
-  type="warning"
-  title="Low Disk Space"
-  onClose={() => {}}
->
-  Drive C: has only 640KB remaining.
-</Alert>
-```
+| Component | Purpose |
+|---|---|
+| `Button` | DOS-style buttons (primary, secondary, ghost, link) on React Aria `Button` |
+| `Input` | Text input with error variant, React Aria `TextField` |
+| `Checkbox` | `[X]`-bracket indicator, React Aria `Checkbox` |
+| `Switch` | Toggle on/off, React Aria `Switch` |
+| `Tabs` | Tabbed navigation on React Aria `TabList/Tab/TabPanel` |
+| `FilterBar` | Multi-select toggle group for faceted filtering |
 
-### Input
+</details>
 
-```tsx
-<Input
-  label="Filename"
-  placeholder="Enter filename..."
-/>
-
-<Input
-  variant="error"
-  errorMessage="File not found"
-  placeholder="Invalid path"
-/>
-```
+<details>
+<summary><strong>Chat &amp; media</strong> — ChatMessage, ChatHistory, ChatInput, ChatContainer, DosFigure, Icon, InlineLink, InlineExpand</summary>
 
-### Checkbox
+| Component | Purpose |
+|---|---|
+| `ChatMessage` | Chat message with role-based DOS styling and streaming cursor |
+| `ChatHistory` | Scrollable message list with auto-scroll + `role="log"` |
+| `ChatInput` | Multiline textarea with Enter-to-send |
+| `ChatContainer` | Composes ChatHistory + ChatInput — drop inside Terminal |
+| `DosFigure` | Demoscene painted-screen media placeholder with scanline sweep |
+| `Icon` | SVG icons backed by pixelarticons |
+| `InlineLink` | In-flow anchor with dotted underline + `▸` / `↗` glyph |
+| `InlineExpand` | Inline disclosure widget for prose |
 
-```tsx
-<Checkbox label="Remember me" />
-<Checkbox label="Accept terms" checked />
-<Checkbox label="Select all" indeterminate />
-```
+</details>
 
-### CommandPrompt
+<details>
+<summary><strong>Time &amp; effects</strong> — TimelineContainer, TimelineNode, TextScramble, RetroEffects, Tokens</summary>
 
-```tsx
-<CommandPrompt
-  prompt="C:\>"
-  onCommand={(cmd) => console.log('Executing:', cmd)}
-  autoFocus
-/>
-```
+| Component | Purpose |
+|---|---|
+| `TimelineContainer` | Multi-zoom timeline (year / month / day / hour views) |
+| `TimelineNode` | Axis markers with shape variants and glow |
+| `TextScramble` | DOS text decode animation |
+| `RetroEffects` | CRT scanlines, noise, phosphor glow |
+| `Tokens` | Design-token reference display (Storybook only) |
+
+</details>
 
-## Design Tokens
+## Design tokens
 
-The library uses authentic CGA colors via CSS custom properties:
+Authentic 16-color CGA palette plus amber/phosphor variants, exposed as CSS custom properties:
 
 ```css
---color-cga-amber: #FFB000;       /* Primary accent */
+--color-cga-amber: #FFB000;         /* Primary accent */
 --color-cga-amber-bright: #FDCA9F;
 --color-cga-amber-dim: #9A5700;
---color-cga-black: #020003;       /* Background */
-/* ... full 16-color CGA palette */
+--color-cga-black: #020003;         /* Background */
+/* …16-color CGA palette + semantic tokens */
 ```
 
-### Theming
+Semantic tokens (`--color-semantic-*`) and Tailwind classes (`bg-dos-*`, `text-dos-*`, `border-dos-*`) are the preferred surface — the raw CGA names are primitives. Full reference in [`src/styles/tokens.css`](./src/styles/tokens.css) or in Storybook's Tokens page.
 
-Apply themes via `data-theme` attribute:
+**Theming** is attribute-driven:
 
 ```html
-<div data-theme="amber-mono">
-  <!-- Amber-on-black terminal aesthetic -->
-</div>
+<div data-theme="amber-mono">…</div>
 ```
 
-Available themes: `amber-mono`, `cga-amber`, `cga-mode4-p0`, `cga-mode4-p1`, `cga-mode5`.
-
-### Tailwind Token Classes
-
-**CGA Colors:** `cga-black`, `cga-blue`, `cga-green`, `cga-cyan`, `cga-red`, `cga-magenta`, `cga-brown`, `cga-light-gray`, `cga-dark-gray`, `cga-bright-blue`, `cga-bright-green`, `cga-bright-cyan`, `cga-bright-red`, `cga-bright-magenta`, `cga-yellow`, `cga-white`, `cga-amber`, `cga-amber-bright`, `cga-amber-dim`
-
-**Semantic Colors:** `dos-bg-primary`, `dos-bg-secondary`, `dos-text-primary`, `dos-text-accent`, `dos-border-default`, `dos-border-focus`, `dos-success`, `dos-warning`, `dos-error`, `dos-info`
-
-**Typography:** `font-dos` (Flexi IBM VGA True v2), `text-dos-text-xs` through `text-dos-display-2xl`, `leading-dos-text-xs` through `leading-dos-display-2xl`
-
-**Spacing:** 4px grid via design tokens
-
-**Border Radius:** `rounded-dos-sm` (2px), `rounded-dos-base` (4px max)
-
 ## Development
 
 ```bash
-npm install           # Install dependencies
-npm run storybook     # Launch Storybook on port 6006
-npm run build         # Production build
-npm run test          # Run test suite
-npm run lint          # ESLint
+npm install
+npm run storybook        # Launch Storybook on :6006
+npm run build            # Production build (tsup + tsc)
+npm run test             # Jest + React Testing Library
+npm run lint             # ESLint
+npm run build-tokens     # Rebuild tokens from src/tokens/*.json
 ```
 
-## Design Philosophy
-
-The DOS aesthetic represents values we've lost in modern software:
+## Design notes
 
-- **Control** - Every command is explicit and intentional
-- **Clarity** - Information presented without distraction
-- **Personal Sovereignty** - Your tools, your way
+eiDotter commits to the constraints that other "DOS-inspired" systems relax:
 
-eiDotter brings these values to modern interfaces while maintaining accessibility (WCAG AA) and usability standards. The authentic 16-color CGA palette plus amber phosphor variants creates that terminal feel without sacrificing readability.
+- **16 colors, no more.** The palette is a historical fact, not a starting point. Extensions (amber, green, phosphor variants) are declared themes, not ad-hoc hex codes.
+- **Single-weight typography.** Flexi IBM VGA True is a bitmap font; there's no bold. All `fontWeight` tokens resolve to `400` and `font-synthesis: none` blocks browser faux-bold. Emphasis comes from color, uppercase on labels, or inverse video — never weight.
+- **Phosphor as physics, not decoration.** Warmup animations, glow layers, and scanline effects are wired into component states; consumers don't opt in per-component.
+- **Keyboard-first.** React Aria powers every interactive component. Focus rings are loud amber on amber-dim. `prefers-reduced-motion` and `prefers-contrast` are honored across the board.
+- **Tree-shakable, no CSS-in-JS.** Runtime deps are minimal and on-purpose: [React Aria](https://react-spectrum.adobe.com/react-aria/) + [pixelarticons](https://github.com/halfmage/pixelarticons), both MIT. Component CSS ships compiled; you pay no CSS-in-JS cost at runtime.
 
-Part of the **Timeline OS** ecosystem - a vision for personal data management along temporal, thematic, and social axes.
+The aesthetic is a constraint the system holds itself to — not a theme that can be turned off.
 
 ## License
 
-CC-BY-NC-4.0 (Creative Commons Attribution-NonCommercial 4.0 International)
+[CC-BY-NC-4.0](./LICENSE.md) — Creative Commons Attribution-NonCommercial 4.0 International. Bundled third-party licenses (pixelarticons MIT, Flexi IBM VGA True CC BY-SA 4.0) attributed in `LICENSE.md`.

package/dist/components/Brand/components/BrandLockup.d.ts

@@ -0,0 +1,20 @@
+import React from 'react';
+import type { HTMLAttributes } from 'react';
+export interface BrandLockupProps extends HTMLAttributes<HTMLDivElement> {
+    /** Logo size in pixels. Defaults to 32. */
+    logoSize?: number | string;
+    /** Render only the logo (no wordmark). */
+    iconOnly?: boolean;
+    /** Render only the wordmark (no logo). */
+    wordmarkOnly?: boolean;
+    /** Add amber phosphor glow on both logo + wordmark. Defaults to true. */
+    glow?: boolean;
+}
+/**
+ * eiDotter brand lockup — Logo + Wordmark composed horizontally.
+ *
+ * The canonical public-facing brand mark. Scales by setting the host's
+ * `font-size` (wordmark) and `logoSize` prop (icon). The two should stay
+ * proportional: roughly `logoSize ≈ font-size × 1.75`.
+ */
+export declare const BrandLockup: React.ForwardRefExoticComponent<BrandLockupProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/Brand/components/Logo.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+import type { SVGProps } from 'react';
+import './Brand.css';
+export interface LogoProps extends Omit<SVGProps<SVGSVGElement>, 'viewBox' | 'children'> {
+    /** Icon size in pixels. Defaults to 32. Pass a number or CSS-valid string. */
+    size?: number | string;
+    /** Add the amber phosphor drop-shadow glow. Defaults to true. */
+    glow?: boolean;
+    /** Accessible label. Defaults to "eiDotter". Set to empty string for decorative use. */
+    title?: string;
+}
+/**
+ * eiDotter brand mark — V2 yolk (pure, no legs).
+ *
+ * The "payload" of the eiDotter identity — a bright CGA amber yolk with a soft
+ * highlight and specular, no shell or drip ornamentation. Scales cleanly from
+ * 16px (favicon) to hero sizes without the 1px shell outline collapsing into
+ * mush at small sizes.
+ *
+ * Fill colors are brand-locked (explicit amber hexes) rather than themed so the
+ * mark reads identically across themes. Consumers who need a non-amber treatment
+ * can override the SVG fills via the `style` prop or by recoloring the child
+ * `<circle>` elements through a CSS selector.
+ */
+export declare const Logo: React.ForwardRefExoticComponent<Omit<LogoProps, "ref"> & React.RefAttributes<SVGSVGElement>>;

package/dist/components/Brand/components/Wordmark.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import type { HTMLAttributes } from 'react';
+import './Brand.css';
+export interface WordmarkProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Add the amber phosphor text-shadow glow. Defaults to true. */
+    glow?: boolean;
+}
+/**
+ * eiDotter wordmark — "eiDotter" with the "ei" prefix dimmed against the full-bright "Dotter".
+ *
+ * Uses the primary DOS font (Flexi IBM VGA True) and the amber phosphor palette.
+ * Sized via `font-size` on the host; the component does not set its own size by
+ * default so it inherits from the surrounding type scale. Wrap in a heading
+ * element if you need semantic weight.
+ */
+export declare const Wordmark: React.ForwardRefExoticComponent<WordmarkProps & React.RefAttributes<HTMLSpanElement>>;

package/dist/components/Brand/components/index.d.ts

@@ -0,0 +1,6 @@
+export { Logo } from './Logo';
+export type { LogoProps } from './Logo';
+export { Wordmark } from './Wordmark';
+export type { WordmarkProps } from './Wordmark';
+export { BrandLockup } from './BrandLockup';
+export type { BrandLockupProps } from './BrandLockup';

package/dist/components/Brand/index.d.ts

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