@ekanos/ui 0.1.1 → 0.1.3

package/README.md

@@ -21,6 +21,8 @@ One subpath per component, mirroring the `@kit/ui` names:
 | `@ekanos/ui/select`          | `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, …                                    |
 | `@ekanos/ui/form`            | `Form`, `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`, `useFormField` |
 | `@ekanos/ui/input`           | `Input`                                                                                                       |
+| `@ekanos/ui/textarea`        | `Textarea`                                                                                                    |
+| `@ekanos/ui/switch`          | `Switch`                                                                                                      |
 | `@ekanos/ui/dropdown-menu`   | `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, …                           |
 | `@ekanos/ui/label`           | `Label`                                                                                                       |
 | `@ekanos/ui/skeleton`        | `Skeleton`                                                                                                    |
@@ -31,37 +33,170 @@ One subpath per component, mirroring the `@kit/ui` names:
 | `@ekanos/ui/spinner`         | `Spinner`                                                                                                     |
 | `@ekanos/ui/ai-prompt-input` | `PromptInput` compound components for AI ask surfaces                                                         |
 
-Most source files are a thin `export * from '@kit/ui/<name>'` — for those,
-`@kit/ui` stays the single source of truth. At build time the `@kit/ui` code is
-inlined into `dist/` so the published artifact has no workspace dependencies
-(`scripts/pack-test.mjs` fails the build if any `@kit/` specifier leaks).
+Most source files are a thin re-export of the internal `@kit/ui` library — for
+those, `@kit/ui` stays the single source of truth. At build time that code is
+inlined into `dist/` so the published artifact has no workspace dependencies;
+`pnpm --filter @ekanos/ui pack:test` fails the build if any `@kit/` specifier
+leaks into the tarball.
 
 Three subpaths — `if`, `trans`, and `spinner` — are instead implemented
-natively in `src/_impl/`. Their `@kit/ui` counterparts live in
-`packages/ui/src/makerkit/`, which is Makerkit-authored code from the
-commercial Turbo starter this monorepo was built on; publishing it under this
+natively here. Their internal counterparts are Makerkit-authored code from the
+commercial Turbo starter this monorepo was built on; publishing that under this
 package's MIT license would purport to grant reuse rights we do not hold. The
-implementations here are original, and `pack:test` fails the build if any
-`packages/ui/src/makerkit` source is ever inlined into `dist/`. Inside the
-monorepo, first-party code keeps using `@kit/ui` as before.
+implementations shipped here are original, and `pack:test` fails the build if
+any Makerkit-authored source is ever inlined into `dist/`.
 
-## Styling: this package ships NO CSS
+## Styling
 
-Components emit Tailwind class strings referencing Fusion's **semantic design
-tokens** (`bg-primary`, `text-muted-foreground`, `border-border`, …). They
-render correctly only inside a host that owns that CSS — the Fusion app or the
-integration dev harness. Nothing here reads or requires the host's
-`theme-tokens.ts` runtime; the contract is purely "the host page loads
-Fusion's stylesheet".
+Every component emits Tailwind class strings bound to Fusion's semantic design
+tokens (`bg-primary`, `text-muted-foreground`, `border-border`, `shadow-card`,
+…), so something has to define those. This package ships that CSS.
 
-Two host-provided assets to know about:
+Pick **one** of the two paths. Loading both means two copies of every utility.
 
-- **Tailwind tokens**: the host defines the semantic token variables and
-  utilities. Without them the components render unstyled HTML.
-- **Icons are Font Awesome**: `Icon` renders `<i class="fa-solid fa-house">`
-  styled by the Font Awesome Pro web-font CSS the host loads. Legacy PascalCase
-  Lucide names are translated to FA equivalents via a bundled map; there is no
-  `lucide-react` at runtime.
+### You do NOT use Tailwind — import the compiled stylesheet
+
+```ts
+import '@ekanos/ui/styles.css';
+```
+
+Self-contained: Tailwind's Preflight, the design tokens, light and dark, and
+every utility class the components in this package emit — all pre-compiled.
+Nothing else to install, no build step, no config. Works in Next.js, Vite, CRA,
+a plain `<link rel="stylesheet">`, anything.
+
+### You DO use Tailwind v4 — import the preset
+
+```css
+@import 'tailwindcss';
+@import '@ekanos/ui/theme.css';
+```
+
+That registers the token map (`--color-primary` → `--primary`, the `--radius-*`
+scale, `shadow-card`), the token values for both themes, the base rules, the
+`dark:` variant, and an `@source` pointing at this package's bundles so your
+Tailwind build generates the components' utilities itself. You then get the
+Fusion tokens in **your own** class strings too.
+
+Also published, if you want the pieces separately: `@ekanos/ui/tokens.css`
+(just the custom properties, no Tailwind at-rules) and `@ekanos/ui/base.css`
+(the base rules).
+
+### What `styles.css` does and does not contain
+
+It contains the utilities **this package's components** emit — derived by
+compiling every class string found in the built bundles. It is not a copy of
+Tailwind.
+
+So `<Button>` and `<Card>` render correctly, but a Tailwind class *you* write in
+*your* component (`p-8`, `grid-cols-3`, `h-5 w-5`) has no rule in it and will do
+nothing. That is inherent: a pre-compiled stylesheet cannot know class names
+that don't exist yet. Two options, both fine:
+
+- style your own markup with plain CSS or inline styles, or
+- take the Tailwind path above, which is how Fusion itself works.
+
+`styles.css` includes Tailwind's Preflight, which is a global reset — it will
+normalise margins, headings and form controls across your whole page. If that
+is unwelcome, use the Tailwind path and control layering yourself.
+
+### Page background and dark mode
+
+The stylesheet will not repaint your page uninvited. To adopt Fusion's page
+surface — which is what makes dark mode look right rather than dark cards
+floating on a white page — add the opt-in class:
+
+```html
+<body class="ekanos-root">
+```
+
+Dark mode resolves in three states, in this order:
+
+| State                                     | Result                       |
+| ----------------------------------------- | ---------------------------- |
+| nothing set                               | light                        |
+| `@media (prefers-color-scheme: dark)`     | dark                         |
+| `.dark` or `[data-theme='dark']` ancestor | dark, beating the media query |
+| `.light` or `[data-theme='light']` on `:root` | light, beating the media query |
+
+So a partner app with no theme toggle at all still follows the OS, and one with
+a toggle (next-themes, or your own) works by setting the class. Fusion itself is
+class-only; the media query is added here for apps that have no switcher.
+
+### Tokens: exactly the ones the components use
+
+`tokens.css` is not a copy of Fusion's `shadcn-ui.css`. It carries the 25
+semantic colour tokens the published components actually reference, plus their
+paired foregrounds, `--radius`, and the one elevation level any of them uses
+(`--el-card`, behind `shadow-card`). Fusion's chart, sidebar and assistant
+tokens, and nine of its ten elevation levels, are deliberately absent.
+
+The build enforces this in both directions: it re-compiles the same class
+strings against Fusion's **full** token map and fails if a component has started
+using a token this package doesn't ship (which would otherwise emit no CSS at
+all, silently). The CSS build enforces it.
+
+### Fonts
+
+Fusion pairs **Figtree** (body) with **Bricolage Grotesque** (headings) and
+loads them via `next/font`. This package only names them in `--font-sans` /
+`--font-heading`, followed by a system fallback stack — no webfont is bundled or
+fetched. For exact typographic parity, load them yourself:
+
+```html
+<link
+  rel="stylesheet"
+  href="https://fonts.googleapis.com/css2?family=Figtree:wght@300..700&family=Bricolage+Grotesque:wght@200..800&display=swap"
+/>
+```
+
+Without them, everything still renders — in your platform's UI font.
+
+### Icons: you must supply Font Awesome
+
+`Icon` renders Font Awesome markup (`<i class="fa-solid fa-house">`) and this
+package ships **no icon font**, because Fusion uses **Font Awesome Pro** (7.2.0,
+© Fonticons, Inc.) under a commercial licence. Redistributing it inside an MIT
+package would hand reuse rights we do not hold to everyone who installs this;
+`pack:test` fails the build if any font data ever reaches `dist/`.
+
+**If you hold a Font Awesome Pro licence**, load your own Pro CSS (or kit) and
+every icon renders exactly as it does in Fusion.
+
+**If you do not**, use Font Awesome Free — but read this, because the fit is
+imperfect:
+
+```sh
+npm install @fortawesome/fontawesome-free
+```
+
+```ts
+import '@fortawesome/fontawesome-free/css/all.min.css';
+```
+
+Free ships `fa-solid`, `fa-regular` and `fa-brands`. It has **no `fa-light` or
+`fa-duotone` family**, and it is missing many Pro glyphs — and `fa-light` is
+exactly what `@kit/ui`'s resolver falls back to for an icon name it doesn't
+recognise. Force everything into a family Free actually has:
+
+```tsx
+import { IconStyleOverrideProvider } from '@ekanos/ui/icon';
+
+<IconStyleOverrideProvider value="solid">{children}</IconStyleOverrideProvider>;
+```
+
+Any glyph Free still doesn't have falls back to a question mark rather than
+vanishing (`--ekanos-icon-fa-fallback`, default `'\f059'`).
+
+**If you load no Font Awesome at all**, icons do not disappear silently: this
+package's CSS draws a placeholder box (`□`) in their place, so "I forgot the
+icon font" is visibly different from "my code is broken". Change or disable it
+with `--ekanos-icon-fallback`.
+
+Note that FA glyphs are sized by `font-size`, not box dimensions, and `Icon`
+derives that from the first `h-*` / `w-*` / `size-*` token in `className` in JS
+— so `<Icon className="h-5 w-5" />` is the right *visual* size even on the
+no-Tailwind path where those utilities have no CSS rule.
 
 ## Runtime notes
 
@@ -110,14 +245,37 @@ runtime is a declared dependency of this package.
 ## Building / verifying
 
 ```bash
-pnpm --filter @ekanos/ui build      # tsup → dist/ (ESM + .d.ts per subpath)
-pnpm --filter @ekanos/ui pack:test  # clean-room publish gate (see scripts/pack-test.mjs)
+pnpm --filter @ekanos/ui build      # tsup → dist/, then the CSS build → the stylesheets
+pnpm --filter @ekanos/ui pack:test  # clean-room publish gate
 ```
 
+The build runs in two stages, in this order for a reason: `tsup` bundles the
+components, then the CSS build scans the *built* `dist/*.js` for class
+strings and compiles exactly those through Tailwind. Deriving the utility set
+from the build output rather than a hand-kept list is what makes it impossible
+to add a component whose classes have no CSS.
+
+That script carries three fatal gates:
+
+- **dangling** — every `var(--x)` the token map reaches for must be defined.
+- **coverage** — the same class strings are re-compiled against Fusion's full
+  token map, and the build fails if a component has begun using a token this
+  package doesn't ship. Without this, such a utility would just silently emit
+  nothing.
+- **lockstep** — `tokens.css` spells its dark values out twice (a media query
+  and an explicit selector, because CSS can't share a block between them); both
+  must stay in agreement.
+
 `pack:test` packs the tarball, asserts dist-only contents, fails on any
 `@kit/` leak, asserts `'use client'` preservation, then installs the tarball
 into a temp project outside the workspace and typechecks
 (`skipLibCheck: false`) + esbuild-bundles a consumer importing every subpath.
 
+It also gates the stylesheets: all four must ship, clear a size floor, still
+contain known utilities and both theme states, resolve through esbuild as
+`@ekanos/ui/styles.css`, and carry **no** icon-font data — `@font-face`, a
+webfont reference or a glyph table in `dist/` fails the build, for the same
+licensing reason the Makerkit lineage check exists.
+
 `prepack` runs the build, so a publish can never ship a stale or missing
 `dist/`.